The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Add upload file in twenty client (#18129)
martmullba59ab809401
diff --git a/packages/twenty-docs/developers/extend/capabilities/apps.mdx b/packages/twenty-docs/developers/extend/capabilities/apps.mdxindex faad8edc8d1..be767e48c14 100644--- a/packages/twenty-docs/developers/extend/capabilities/apps.mdx+++ b/packages/twenty-docs/developers/extend/capabilities/apps.mdx@@ -793,6 +793,51 @@ Notes:- The API key's permissions are determined by the role referenced in your `application-config.ts` via `defaultRoleUniversalIdentifier`. This is the default role used by logic functions of your application.- Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `defaultRoleUniversalIdentifier` to that role's universal identifier.+#### Uploading files++The generated `Twenty` client includes an `uploadFile` method for attaching files to file-type fields on your workspace objects. Because standard GraphQL clients do not support multipart file uploads natively, the client provides this dedicated method that implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec) under the hood.++```typescript+import Twenty from '~/generated';+import * as fs from 'fs';++const client = new Twenty();++const fileBuffer = fs.readFileSync('./invoice.pdf');++const uploadedFile = await client.uploadFile(+ fileBuffer, // file contents as a Buffer+ 'invoice.pdf', // filename+ 'application/pdf', // MIME type (defaults to 'application/octet-stream')+ '58a0a314-d7ea-4865-9850-7fb84e72f30b', // field universal identifier+);++console.log(uploadedFile);+// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }+```++The method signature:++```typescript+uploadFile(+ fileBuffer: Buffer,+ filename: string,+ contentType: string,+ fieldMetadataUniversalIdentifier: string,+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>+```++| Parameter | Type | Description |+|-----------|------|-------------|+| `fileBuffer` | `Buffer` | The raw file contents |+| `filename` | `string` | The name of the file (used for storage and display) |+| `contentType` | `string` | MIME type of the file (defaults to `application/octet-stream` if omitted) |+| `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |++Key points:+- The method sends the file to the **metadata endpoint** (not the main GraphQL endpoint), where the upload mutation is resolved.+- It uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed — consistent with how apps reference fields everywhere else.+- The returned `url` is a signed URL you can use to access the uploaded file.### Hello World examplediff --git a/packages/twenty-front/src/generated-metadata/graphql.ts b/packages/twenty-front/src/generated-metadata/graphql.tsindex c8aa14be5d6..57b72c70ad9 100644--- a/packages/twenty-front/src/generated-metadata/graphql.ts+++ b/packages/twenty-front/src/generated-metadata/graphql.ts@@ -2333,6 +2333,7 @@ export type Mutation = {/** @deprecated Use uploadFilesFieldFile instead */uploadFile: SignedFile;uploadFilesFieldFile: FileWithSignedUrl;+ uploadFilesFieldFileByUniversalIdentifier: FileWithSignedUrl;uploadImage: SignedFile;uploadWorkflowFile: FileWithSignedUrl;uploadWorkspaceLogo: FileWithSignedUrl;@@ -3152,6 +3153,12 @@ export type MutationUploadFilesFieldFileArgs = {};+export type MutationUploadFilesFieldFileByUniversalIdentifierArgs = {+ fieldMetadataUniversalIdentifier: Scalars['String'];+ file: Scalars['Upload'];+};++export type MutationUploadImageArgs = {file: Scalars['Upload'];fileFolder?: InputMaybe<FileFolder>;diff --git a/packages/twenty-sdk/src/cli/utilities/client/client-service.ts b/packages/twenty-sdk/src/cli/utilities/client/client-service.tsindex dc1241d046f..b0620318fcd 100644--- a/packages/twenty-sdk/src/cli/utilities/client/client-service.ts+++ b/packages/twenty-sdk/src/cli/utilities/client/client-service.ts@@ -67,6 +67,7 @@ export class ClientService {const defaultOptions: ClientOptions = {url: \`\${process.env.${DEFAULT_API_URL_NAME}}/graphql\`,+ metadataUrl: \`\${process.env.${DEFAULT_API_URL_NAME}}/metadata\`,headers: {'Content-Type': 'application/json',Authorization: \`Bearer \${process.env.${DEFAULT_API_KEY_NAME}}\`,@@ -75,16 +76,23 @@ const defaultOptions: ClientOptions = {export default class Twenty {private client: Client;+ private url: string;+ private metadataUrl: string;+ private authorizationToken: string;constructor(options?: ClientOptions) {- this.client = createClient({+ const merged: ClientOptions = {...defaultOptions,...options,headers: {...defaultOptions.headers,...(options?.headers ?? {}),},- });+ };+ this.client = createClient(merged);+ this.url = merged.url;+ this.metadataUrl = merged.metadataUrl;+ this.authorizationToken = merged.headers.Authorization;}query<R extends QueryGenqlSelection>(request: R & { __name?: string }) {@@ -94,6 +102,49 @@ export default class Twenty {mutation<R extends MutationGenqlSelection>(request: R & { __name?: string }) {return this.client.mutation(request);}++ async uploadFile(+ fileBuffer: Buffer,+ filename: string,+ contentType: string = 'application/octet-stream',+ fieldMetadataUniversalIdentifier: string,+ ): Promise<{+ id: string;+ path: string;+ size: number;+ createdAt: string;+ url: string;+ }> {+ const form = new FormData();++ form.append(+ 'operations',+ JSON.stringify({+ query: \`mutation UploadFilesFieldFileByUniversalIdentifier($file: Upload!, $fieldMetadataUniversalIdentifier: String!) {+ uploadFilesFieldFileByUniversalIdentifier(file: $file, fieldMetadataUniversalIdentifier: $fieldMetadataUniversalIdentifier) { id path size createdAt url }+ }\`,+ variables: { file: null, fieldMetadataUniversalIdentifier },+ }),+ );+ form.append('map', JSON.stringify({ '0': ['variables.file'] }));+ form.append('0', new Blob([fileBuffer], { type: contentType }), filename);++ const response = await fetch(this.metadataUrl, {+ method: 'POST',+ headers: {+ Authorization: this.authorizationToken,+ },+ body: form,+ });++ const result = await response.json();++ if (result.errors) {+ throw new GenqlError(result.errors, result.data);+ }++ return result.data.uploadFilesFieldFileByUniversalIdentifier;+ }}`;diff --git a/packages/twenty-server/src/engine/core-modules/file/files-field/files-field.exception.ts b/packages/twenty-server/src/engine/core-modules/file/files-field/files-field.exception.tsindex 01b5e9ac896..cef7ce8c670 100644--- a/packages/twenty-server/src/engine/core-modules/file/files-field/files-field.exception.ts+++ b/packages/twenty-server/src/engine/core-modules/file/files-field/files-field.exception.ts@@ -4,6 +4,7 @@ import { CustomException } from 'src/utils/custom-exception';export enum FilesFieldExceptionCode {FILE_DELETION_FAILED = 'FILE_DELETION_FAILED',+ BAD_REQUEST = 'BAD_REQUEST',TEMPORARY_FILE_NOT_ALLOWED = 'TEMPORARY_FILE_NOT_ALLOWED',}diff --git a/packages/twenty-server/src/engine/core-modules/file/files-field/resolvers/files-field.resolver.ts b/packages/twenty-server/src/engine/core-modules/file/files-field/resolvers/files-field.resolver.tsindex e17065b8f53..2ccf58eb556 100644--- a/packages/twenty-server/src/engine/core-modules/file/files-field/resolvers/files-field.resolver.ts+++ b/packages/twenty-server/src/engine/core-modules/file/files-field/resolvers/files-field.resolver.ts@@ -48,4 +48,29 @@ export class FilesFieldResolver {fieldMetadataId,});}++ @Mutation(() => FileWithSignedUrlDto)+ @UseGuards(SettingsPermissionGuard(PermissionFlagType.UPLOAD_FILE))+ async uploadFilesFieldFileByUniversalIdentifier(+ @AuthWorkspace()+ { id: workspaceId }: WorkspaceEntity,+ @Args({ name: 'file', type: () => GraphQLUpload })+ { createReadStream, filename }: FileUpload,+ @Args({+ name: 'fieldMetadataUniversalIdentifier',+ type: () => String,+ nullable: false,+ })+ fieldMetadataUniversalIdentifier: string,+ ): Promise<FileWithSignedUrlDto> {+ const stream = createReadStream();+ const buffer = await streamToBuffer(stream);++ return await this.filesFieldService.uploadFile({+ file: buffer,+ filename,+ workspaceId,+ fieldMetadataUniversalIdentifier,+ });+ }}diff --git a/packages/twenty-server/src/engine/core-modules/file/files-field/services/files-field.service.ts b/packages/twenty-server/src/engine/core-modules/file/files-field/services/files-field.service.tsindex 303b267ed90..53e75f12a93 100644--- a/packages/twenty-server/src/engine/core-modules/file/files-field/services/files-field.service.ts+++ b/packages/twenty-server/src/engine/core-modules/file/files-field/services/files-field.service.ts@@ -35,12 +35,24 @@ export class FilesFieldService {filename,workspaceId,fieldMetadataId,+ fieldMetadataUniversalIdentifier,}: {file: Buffer;filename: string;workspaceId: string;- fieldMetadataId: string;+ fieldMetadataId?: string;+ fieldMetadataUniversalIdentifier?: string;}): Promise<FileWithSignedUrlDto> {+ if (!fieldMetadataId && !fieldMetadataUniversalIdentifier) {+ throw new FilesFieldException(+ 'fieldMetadataId or fieldMetadataUniversalIdentifier must be provided',+ FilesFieldExceptionCode.BAD_REQUEST,+ {+ userFriendlyMessage: msg`fieldMetadataId or fieldMetadataUniversalIdentifier must be provided`,+ },+ );+ }+const { mimeType, ext } = await extractFileInfo({file,filename,@@ -54,7 +66,10 @@ export class FilesFieldService {const fieldMetadata = await this.fieldMetadataRepository.findOneOrFail({select: ['applicationId', 'universalIdentifier'],where: {- id: fieldMetadataId,+ ...(fieldMetadataId ? { id: fieldMetadataId } : {}),+ ...(fieldMetadataUniversalIdentifier+ ? { universalIdentifier: fieldMetadataUniversalIdentifier }+ : {}),workspaceId,},});