@grantjs/schema 1.14.2 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grantjs/schema",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/generated/graphql.ts

@@ -1505,6 +1505,22 @@ export type ProjectSyncJobsQuery = {
   };
 };
 
+export type RequestProjectSyncUploadUrlMutationVariables = Exact<{
+  id: string | number;
+  scope: Types.Scope;
+  input: Types.RequestProjectSyncUploadUrlInput;
+}>;
+
+export type RequestProjectSyncUploadUrlMutation = {
+  requestProjectSyncUploadUrl: {
+    uploadId: string;
+    url: string;
+    method: string;
+    expiresAt: Date;
+    headers: Array<{ name: string; value: string }>;
+  };
+};
+
 export type StartProjectExportMutationVariables = Exact<{
   id: string | number;
   scope: Types.Scope;
@@ -8153,6 +8169,94 @@ export const ProjectSyncJobsDocument = {
     },
   ],
 } as unknown as DocumentNode<ProjectSyncJobsQuery, ProjectSyncJobsQueryVariables>;
+export const RequestProjectSyncUploadUrlDocument = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'mutation',
+      name: { kind: 'Name', value: 'RequestProjectSyncUploadUrl' },
+      variableDefinitions: [
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'id' } },
+          type: {
+            kind: 'NonNullType',
+            type: { kind: 'NamedType', name: { kind: 'Name', value: 'ID' } },
+          },
+        },
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+          type: {
+            kind: 'NonNullType',
+            type: { kind: 'NamedType', name: { kind: 'Name', value: 'Scope' } },
+          },
+        },
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'input' } },
+          type: {
+            kind: 'NonNullType',
+            type: {
+              kind: 'NamedType',
+              name: { kind: 'Name', value: 'RequestProjectSyncUploadUrlInput' },
+            },
+          },
+        },
+      ],
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [
+          {
+            kind: 'Field',
+            name: { kind: 'Name', value: 'requestProjectSyncUploadUrl' },
+            arguments: [
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'id' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'id' } },
+              },
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'scope' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+              },
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'input' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'input' } },
+              },
+            ],
+            selectionSet: {
+              kind: 'SelectionSet',
+              selections: [
+                { kind: 'Field', name: { kind: 'Name', value: 'uploadId' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'url' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'method' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'expiresAt' } },
+                {
+                  kind: 'Field',
+                  name: { kind: 'Name', value: 'headers' },
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'value' } },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  ],
+} as unknown as DocumentNode<
+  RequestProjectSyncUploadUrlMutation,
+  RequestProjectSyncUploadUrlMutationVariables
+>;
 export const StartProjectExportDocument = {
   kind: 'Document',
   definitions: [

package/src/generated/resolvers.ts

@@ -378,6 +378,7 @@ export type ResolversTypes = ResolversObject<{
   ProjectSyncJobSortInput: Types.ProjectSyncJobSortInput;
   ProjectSyncJobSortableField: Types.ProjectSyncJobSortableField;
   ProjectSyncJobStatus: Types.ProjectSyncJobStatus;
+  ProjectSyncUploadUrl: ResolverTypeWrapper<Types.ProjectSyncUploadUrl>;
   ProjectTag: ResolverTypeWrapper<Types.ProjectTag>;
   ProjectUser: ResolverTypeWrapper<Types.ProjectUser>;
   ProjectUserApiKey: ResolverTypeWrapper<Types.ProjectUserApiKey>;
@@ -464,6 +465,7 @@ export type ResolversTypes = ResolversObject<{
   RequestPasswordResetResponse: ResolverTypeWrapper<Types.RequestPasswordResetResponse>;
   RequestProjectAppPictureUploadUrlInput: Types.RequestProjectAppPictureUploadUrlInput;
   RequestProjectPictureUploadUrlInput: Types.RequestProjectPictureUploadUrlInput;
+  RequestProjectSyncUploadUrlInput: Types.RequestProjectSyncUploadUrlInput;
   RequestUserPictureUploadUrlInput: Types.RequestUserPictureUploadUrlInput;
   ResendVerificationInput: Types.ResendVerificationInput;
   ResendVerificationResponse: ResolverTypeWrapper<Types.ResendVerificationResponse>;
@@ -502,6 +504,7 @@ export type ResolversTypes = ResolversObject<{
   String: ResolverTypeWrapper<Types.Scalars['String']['output']>;
   SyncProjectInput: Types.SyncProjectInput;
   SyncProjectResult: ResolverTypeWrapper<Types.SyncProjectResult>;
+  SyncProjectSourceInput: Types.SyncProjectSourceInput;
   Tag: ResolverTypeWrapper<Types.Tag>;
   TagCdmInput: Types.TagCdmInput;
   TagPage: ResolverTypeWrapper<Types.TagPage>;
@@ -759,6 +762,7 @@ export type ResolversParentTypes = ResolversObject<{
   ProjectSyncJob: Types.ProjectSyncJob;
   ProjectSyncJobPage: Types.ProjectSyncJobPage;
   ProjectSyncJobSortInput: Types.ProjectSyncJobSortInput;
+  ProjectSyncUploadUrl: Types.ProjectSyncUploadUrl;
   ProjectTag: Types.ProjectTag;
   ProjectUser: Types.ProjectUser;
   ProjectUserApiKey: Types.ProjectUserApiKey;
@@ -845,6 +849,7 @@ export type ResolversParentTypes = ResolversObject<{
   RequestPasswordResetResponse: Types.RequestPasswordResetResponse;
   RequestProjectAppPictureUploadUrlInput: Types.RequestProjectAppPictureUploadUrlInput;
   RequestProjectPictureUploadUrlInput: Types.RequestProjectPictureUploadUrlInput;
+  RequestProjectSyncUploadUrlInput: Types.RequestProjectSyncUploadUrlInput;
   RequestUserPictureUploadUrlInput: Types.RequestUserPictureUploadUrlInput;
   ResendVerificationInput: Types.ResendVerificationInput;
   ResendVerificationResponse: Types.ResendVerificationResponse;
@@ -878,6 +883,7 @@ export type ResolversParentTypes = ResolversObject<{
   String: Types.Scalars['String']['output'];
   SyncProjectInput: Types.SyncProjectInput;
   SyncProjectResult: Types.SyncProjectResult;
+  SyncProjectSourceInput: Types.SyncProjectSourceInput;
   Tag: Types.Tag;
   TagCdmInput: Types.TagCdmInput;
   TagPage: Types.TagPage;
@@ -1839,6 +1845,12 @@ export type MutationResolvers<
     ContextType,
     RequireFields<Types.MutationRequestProjectPictureUploadUrlArgs, 'input'>
   >;
+  requestProjectSyncUploadUrl?: Resolver<
+    ResolversTypes['ProjectSyncUploadUrl'],
+    ParentType,
+    ContextType,
+    RequireFields<Types.MutationRequestProjectSyncUploadUrlArgs, 'id' | 'input' | 'scope'>
+  >;
   requestUserPictureUploadUrl?: Resolver<
     ResolversTypes['UploadUrl'],
     ParentType,
@@ -2733,6 +2745,18 @@ export type ProjectSyncJobPageResolvers<
   __isTypeOf?: IsTypeOfResolverFn<ParentType, ContextType>;
 }>;
 
+export type ProjectSyncUploadUrlResolvers<
+  ContextType = any,
+  ParentType extends ResolversParentTypes['ProjectSyncUploadUrl'] =
+    ResolversParentTypes['ProjectSyncUploadUrl'],
+> = ResolversObject<{
+  expiresAt?: Resolver<ResolversTypes['Date'], ParentType, ContextType>;
+  headers?: Resolver<Array<ResolversTypes['UploadUrlHeader']>, ParentType, ContextType>;
+  method?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
+  uploadId?: Resolver<ResolversTypes['ID'], ParentType, ContextType>;
+  url?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
+}>;
+
 export type ProjectTagResolvers<
   ContextType = any,
   ParentType extends ResolversParentTypes['ProjectTag'] = ResolversParentTypes['ProjectTag'],
@@ -3760,6 +3784,7 @@ export type Resolvers<ContextType = any> = ResolversObject<{
   ProjectRolePermission?: ProjectRolePermissionResolvers<ContextType>;
   ProjectSyncJob?: ProjectSyncJobResolvers<ContextType>;
   ProjectSyncJobPage?: ProjectSyncJobPageResolvers<ContextType>;
+  ProjectSyncUploadUrl?: ProjectSyncUploadUrlResolvers<ContextType>;
   ProjectTag?: ProjectTagResolvers<ContextType>;
   ProjectUser?: ProjectUserResolvers<ContextType>;
   ProjectUserApiKey?: ProjectUserApiKeyResolvers<ContextType>;

package/src/generated/schema-types.ts

@@ -1191,6 +1191,19 @@ export type Mutation = {
    * is recorded against the project.
    */
   requestProjectPictureUploadUrl: UploadUrl;
+  /**
+   * Ask for a URL to upload a CDM import document directly to storage, so it can be
+   * imported without passing through this API's request body (and its size limit).
+   *
+   * Requires Project sync job update permission in the given project scope, like
+   * `startProjectSync`. The server derives the storage key from the project and a
+   * server-minted `uploadId`; the client never supplies a path. The URL commits to exactly
+   * `input.contentLength` bytes of `application/json`, up to `CDM_UPLOAD_MAX_BYTES`.
+   *
+   * PUT the file, then call `startProjectSync` with `input.source.uploadId`. An upload
+   * that is never started is expired by the storage lifecycle rule.
+   */
+  requestProjectSyncUploadUrl: ProjectSyncUploadUrl;
   /**
    * Ask for a URL to upload another user's picture directly to storage.
    *
@@ -1519,6 +1532,12 @@ export type MutationRequestProjectPictureUploadUrlArgs = {
   input: RequestProjectPictureUploadUrlInput;
 };
 
+export type MutationRequestProjectSyncUploadUrlArgs = {
+  id: Scalars['ID']['input'];
+  input: RequestProjectSyncUploadUrlInput;
+  scope: Scope;
+};
+
 export type MutationRequestUserPictureUploadUrlArgs = {
   input: RequestUserPictureUploadUrlInput;
 };
@@ -2382,6 +2401,28 @@ export enum ProjectSyncJobStatus {
   Running = 'RUNNING',
 }
 
+/**
+ * A bounded, time-limited URL to PUT a CDM import document to, and the id to start the
+ * import from. Same commitments as `UploadUrl`: exactly `contentLength` bytes of exactly
+ * `contentType`, at a path derived on the server from the project, until `expiresAt`.
+ */
+export type ProjectSyncUploadUrl = {
+  __typename?: 'ProjectSyncUploadUrl';
+  /** Instant after which the store refuses the URL. */
+  expiresAt: Scalars['Date']['output'];
+  /** Headers the client must set verbatim. `Content-Length` is deliberately absent. */
+  headers: Array<UploadUrlHeader>;
+  /** HTTP method the client must use. Always PUT today. */
+  method: Scalars['String']['output'];
+  /** Pass as `source.uploadId` to `startProjectSync`. */
+  uploadId: Scalars['ID']['output'];
+  /**
+   * Absolute for object stores; application-relative for targets this API serves
+   * itself. Resolve it against the API origin before using it.
+   */
+  url: Scalars['String']['output'];
+};
+
 export type ProjectTag = Auditable & {
   __typename?: 'ProjectTag';
   createdAt: Scalars['Date']['output'];
@@ -3144,6 +3185,16 @@ export type RequestProjectPictureUploadUrlInput = {
   scope: Scope;
 };
 
+export type RequestProjectSyncUploadUrlInput = {
+  /**
+   * Exact byte length of the CDM JSON file the client will PUT. The URL commits to it,
+   * and it may not exceed `CDM_UPLOAD_MAX_BYTES` (default 64 MiB).
+   */
+  contentLength: Scalars['Int']['input'];
+  /** Defaults to `application/json`, the only type accepted. */
+  contentType?: InputMaybe<Scalars['String']['input']>;
+};
+
 export type RequestUserPictureUploadUrlInput = {
   /**
    * Exact byte length the client will send. Validated against the upload policy
@@ -3499,6 +3550,13 @@ export type StartProjectExportInput = {
 /**
  * Versioned canonical project document (CDM) for export/import: roles, users,
  * resources, permissions, groups, and tags scoped to one project.
+ *
+ * Two shapes. **Inline**: `version`, `roles` and `users` are required and the document is
+ * the input. **By reference**: `source` is set, `mode` still says how to apply it, and
+ * `version` is optional and the entity arrays (`roles`, `users`, `resources`,
+ * `permissions`, `groups`, `tags`) must be absent: the document is the file uploaded
+ * through `requestProjectSyncUploadUrl`, and the worker validates it, so a schema error or
+ * an over-limit entity count surfaces as a `FAILED` job, not as an error on the mutation.
  */
 export type SyncProjectInput = {
   groups?: InputMaybe<Array<GroupCdmInput>>;
@@ -3506,10 +3564,19 @@ export type SyncProjectInput = {
   mode: CdmModeInput;
   permissions?: InputMaybe<Array<PermissionCdmInput>>;
   resources?: InputMaybe<Array<ResourceCdmInput>>;
-  roles: Array<RoleCdmInput>;
+  /** Required inline; must be absent with `source`. */
+  roles?: InputMaybe<Array<RoleCdmInput>>;
+  /**
+   * Import the document uploaded through `requestProjectSyncUploadUrl` instead of sending
+   * it inline. The entity arrays must then be absent, and `mode` (and `version`, if
+   * given) must match the uploaded document.
+   */
+  source?: InputMaybe<SyncProjectSourceInput>;
   tags?: InputMaybe<Array<TagCdmInput>>;
-  users: Array<UserCdmInput>;
-  version: Scalars['Int']['input'];
+  /** Required inline; must be absent with `source`. */
+  users?: InputMaybe<Array<UserCdmInput>>;
+  /** Required inline; optional with `source`, where the uploaded document carries it. */
+  version?: InputMaybe<Scalars['Int']['input']>;
 };
 
 /** Counters and warnings from a completed CDM import. */
@@ -3539,6 +3606,24 @@ export type SyncProjectResult = {
   warnings: Array<Scalars['String']['output']>;
 };
 
+/**
+ * Where the CDM document of a by-reference import is: an upload made through
+ * `requestProjectSyncUploadUrl`. See `SyncProjectInput.source`.
+ */
+export type SyncProjectSourceInput = {
+  /**
+   * How many entities (roles, users, resources, permissions, groups and tags) the
+   * uploaded document holds. A hint, recorded for the job list and never trusted: the
+   * worker counts the document itself.
+   */
+  entityCount?: InputMaybe<Scalars['Int']['input']>;
+  /**
+   * The `uploadId` returned by `requestProjectSyncUploadUrl`. The server derives the
+   * storage key from the project and this id; the client never supplies a path.
+   */
+  uploadId: Scalars['ID']['input'];
+};
+
 export type Tag = Auditable & {
   __typename?: 'Tag';
   color: Scalars['String']['output'];

package/src/operations/projects/request-project-sync-upload-url.graphql

@@ -0,0 +1,16 @@
+mutation RequestProjectSyncUploadUrl(
+  $id: ID!
+  $scope: Scope!
+  $input: RequestProjectSyncUploadUrlInput!
+) {
+  requestProjectSyncUploadUrl(id: $id, scope: $scope, input: $input) {
+    uploadId
+    url
+    method
+    expiresAt
+    headers {
+      name
+      value
+    }
+  }
+}

package/src/schema/projects/inputs/request-project-sync-upload-url.graphql

@@ -0,0 +1,9 @@
+input RequestProjectSyncUploadUrlInput {
+  """
+  Exact byte length of the CDM JSON file the client will PUT. The URL commits to it,
+  and it may not exceed `CDM_UPLOAD_MAX_BYTES` (default 64 MiB).
+  """
+  contentLength: Int!
+  "Defaults to `application/json`, the only type accepted."
+  contentType: String
+}

package/src/schema/projects/inputs/sync-project-cdm.graphql

@@ -153,18 +153,52 @@ input UserCdmInput {
   metadata: JSON
 }
 
+"""
+Where the CDM document of a by-reference import is: an upload made through
+`requestProjectSyncUploadUrl`. See `SyncProjectInput.source`.
+"""
+input SyncProjectSourceInput {
+  """
+  The `uploadId` returned by `requestProjectSyncUploadUrl`. The server derives the
+  storage key from the project and this id; the client never supplies a path.
+  """
+  uploadId: ID!
+  """
+  How many entities (roles, users, resources, permissions, groups and tags) the
+  uploaded document holds. A hint, recorded for the job list and never trusted: the
+  worker counts the document itself.
+  """
+  entityCount: Int
+}
+
 """
 Versioned canonical project document (CDM) for export/import: roles, users,
 resources, permissions, groups, and tags scoped to one project.
+
+Two shapes. **Inline**: `version`, `roles` and `users` are required and the document is
+the input. **By reference**: `source` is set, `mode` still says how to apply it, and
+`version` is optional and the entity arrays (`roles`, `users`, `resources`,
+`permissions`, `groups`, `tags`) must be absent: the document is the file uploaded
+through `requestProjectSyncUploadUrl`, and the worker validates it, so a schema error or
+an over-limit entity count surfaces as a `FAILED` job, not as an error on the mutation.
 """
 input SyncProjectInput {
-  version: Int!
+  "Required inline; optional with `source`, where the uploaded document carries it."
+  version: Int
   id: String
   mode: CdmModeInput!
-  roles: [RoleCdmInput!]!
-  users: [UserCdmInput!]!
+  "Required inline; must be absent with `source`."
+  roles: [RoleCdmInput!]
+  "Required inline; must be absent with `source`."
+  users: [UserCdmInput!]
   resources: [ResourceCdmInput!]
   permissions: [PermissionCdmInput!]
   groups: [GroupCdmInput!]
   tags: [TagCdmInput!]
+  """
+  Import the document uploaded through `requestProjectSyncUploadUrl` instead of sending
+  it inline. The entity arrays must then be absent, and `mode` (and `version`, if
+  given) must match the uploaded document.
+  """
+  source: SyncProjectSourceInput
 }

package/src/schema/projects/mutations/request-project-sync-upload-url.graphql

@@ -0,0 +1,19 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload a CDM import document directly to storage, so it can be
+  imported without passing through this API's request body (and its size limit).
+
+  Requires Project sync job update permission in the given project scope, like
+  `startProjectSync`. The server derives the storage key from the project and a
+  server-minted `uploadId`; the client never supplies a path. The URL commits to exactly
+  `input.contentLength` bytes of `application/json`, up to `CDM_UPLOAD_MAX_BYTES`.
+
+  PUT the file, then call `startProjectSync` with `input.source.uploadId`. An upload
+  that is never started is expired by the storage lifecycle rule.
+  """
+  requestProjectSyncUploadUrl(
+    id: ID!
+    scope: Scope!
+    input: RequestProjectSyncUploadUrlInput!
+  ): ProjectSyncUploadUrl!
+}

package/src/schema/projects/types/project-sync-upload-url.graphql

@@ -0,0 +1,24 @@
+"""
+A bounded, time-limited URL to PUT a CDM import document to, and the id to start the
+import from. Same commitments as `UploadUrl`: exactly `contentLength` bytes of exactly
+`contentType`, at a path derived on the server from the project, until `expiresAt`.
+"""
+type ProjectSyncUploadUrl {
+  "Pass as `source.uploadId` to `startProjectSync`."
+  uploadId: ID!
+
+  """
+  Absolute for object stores; application-relative for targets this API serves
+  itself. Resolve it against the API origin before using it.
+  """
+  url: String!
+
+  "HTTP method the client must use. Always PUT today."
+  method: String!
+
+  "Headers the client must set verbatim. `Content-Length` is deliberately absent."
+  headers: [UploadUrlHeader!]!
+
+  "Instant after which the store refuses the URL."
+  expiresAt: Date!
+}

package/src/sdl-contract.test.ts

@@ -50,10 +50,11 @@ describe('operation documents', () => {
   // project-app pictures (eight operation documents).
   // 135 after project OAuth connections: get/upsert/clear (three operation documents).
   // 136 after closed-install: AuthSignupPolicyDocument (publicSignupEnabled, bootstrapOpen).
+  // 137 after CDM imports by reference: RequestProjectSyncUploadUrlDocument.
   // Updating this number is the point of the pin, not a nuisance: every change
   // to it should be a line in a commit message.
   it('finds every document under src/operations', () => {
-    expect(files).toHaveLength(136);
+    expect(files).toHaveLength(137);
   });
 
   it.each(files.map((f) => [relative(process.cwd(), f), f]))('%s validates', (_label, file) => {