@opengeni/contracts 0.50.0 → 1.0.0

package/src/external-identities.ts

@@ -0,0 +1,285 @@
+import { z } from "zod";
+import { Permission } from "./permissions";
+
+// External identifiers are opaque, case-sensitive strings. In particular a
+// native-looking identifier is still host data, never a native subject claim.
+// Bound bytes, not just JS code units: these values share a PostgreSQL B-tree
+// index entry. Never normalize/truncate an identifier to make it fit, and reject
+// text that the driver would replace or PostgreSQL cannot represent.
+const encoder = new TextEncoder();
+function opaqueText(maxBytes: number) {
+  return z
+    .string()
+    .min(1)
+    .max(maxBytes)
+    .refine(
+      (value) =>
+        !value.includes("\0") &&
+        !/[\uD800-\uDFFF]/u.test(value) &&
+        encoder.encode(value).byteLength <= maxBytes,
+      {
+        message: `Identifier must be valid PostgreSQL Unicode text of at most ${maxBytes} UTF-8 bytes`,
+      },
+    );
+}
+const externalId = opaqueText(1024);
+const source = opaqueText(200);
+const externalSubject = z
+  .string()
+  .regex(/^external_user:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$(?![\s\S])/);
+const nativeSubject = z
+  .string()
+  .min(1)
+  .max(1024)
+  .regex(/^user:[^\r\n]+$(?![\s\S])/);
+export const ExternalIdentityReference = z
+  .object({
+    externalId,
+    source: source.default("default"),
+  })
+  .strict();
+export type ExternalIdentityReference = z.infer<typeof ExternalIdentityReference>;
+
+export const AddExternalWorkspaceMemberRequest = z
+  .object({
+    identity: ExternalIdentityReference,
+    permissions: z.array(Permission).min(1).max(Permission.options.length),
+    /** Opt-in durable operation identity; unkeyed legacy requests are not cancellable. */
+    operationId: z.string().uuid().optional(),
+  })
+  .strict();
+export type AddExternalWorkspaceMemberRequest = z.infer<typeof AddExternalWorkspaceMemberRequest>;
+
+/** Content-free service lookup, including identities which can no longer act. */
+export const ExternalIdentityLookup = z.discriminatedUnion("found", [
+  z.object({ found: z.literal(false) }).strict(),
+  z
+    .object({
+      found: z.literal(true),
+      subjectId: externalSubject,
+      organizationMembershipId: z.string().uuid(),
+      identityStatus: z.enum(["active", "disabled", "revoked"]),
+      identityAuthorizationRevision: z.number().int().positive().safe(),
+      membershipStatus: z.enum(["provisioning", "active", "suspended", "revoked"]),
+      membershipAuthorizationRevision: z.number().int().positive().safe(),
+    })
+    .strict(),
+]);
+export type ExternalIdentityLookup = z.infer<typeof ExternalIdentityLookup>;
+
+/** Terminal withdrawal of this external member's workspace access, also fencing
+ * an exact earlier onboarding operation whether or not it has reached the API. */
+export const CancelExternalWorkspaceMemberGrantRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    cancelGrantOperationId: z.string().uuid(),
+  })
+  .strict()
+  .refine((value) => value.operationId !== value.cancelGrantOperationId, {
+    message: "Revocation and grant must use different operation identities",
+  });
+export type CancelExternalWorkspaceMemberGrantRequest = z.infer<
+  typeof CancelExternalWorkspaceMemberGrantRequest
+>;
+export const CancelExternalWorkspaceMemberGrantResponse = z
+  .object({
+    removed: z.boolean(),
+    replay: z.boolean(),
+    fencedGrantOperationId: z.string().uuid(),
+  })
+  .strict();
+export type CancelExternalWorkspaceMemberGrantResponse = z.infer<
+  typeof CancelExternalWorkspaceMemberGrantResponse
+>;
+
+/** Replace an existing external member's permissions in one shared workspace.
+ * Keyed and idempotent like a grant; narrowing forces live authority to
+ * re-check but never cancels or tears down work. */
+export const UpdateExternalWorkspaceMemberRequest = z
+  .object({
+    permissions: z.array(Permission).min(1).max(Permission.options.length),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type UpdateExternalWorkspaceMemberRequest = z.infer<
+  typeof UpdateExternalWorkspaceMemberRequest
+>;
+export const UpdateExternalWorkspaceMemberResponse = z
+  .object({
+    subjectId: z.string(),
+    organizationMembershipId: z.string().uuid(),
+    permissions: z.array(Permission),
+    /** True when a previously held permission was removed. */
+    narrowed: z.boolean(),
+    replay: z.boolean(),
+  })
+  .strict();
+export type UpdateExternalWorkspaceMemberResponse = z.infer<
+  typeof UpdateExternalWorkspaceMemberResponse
+>;
+
+/** Uses the organization membership ID returned by lazy identity admission.
+ * Reactivation restores admission only, not revoked work or workspace grants. */
+export const UpdateExternalIdentityMembershipRequest = z
+  .object({
+    kind: z.enum(["suspend", "reactivate", "offboard"]),
+    expectedAuthorizationRevision: z.number().int().positive().safe(),
+    operationId: z.string().uuid(),
+    reason: z.string().max(512).optional(),
+  })
+  .strict();
+export type UpdateExternalIdentityMembershipRequest = z.infer<
+  typeof UpdateExternalIdentityMembershipRequest
+>;
+
+export const ExternalActorSelection = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("external"), identity: ExternalIdentityReference }).strict(),
+  z
+    .object({
+      mode: z.literal("linked_native"),
+      identity: ExternalIdentityReference,
+      linkId: z.string().uuid(),
+      expectedLinkRevision: z.number().int().positive().safe(),
+    })
+    .strict(),
+]);
+export type ExternalActorSelection = z.infer<typeof ExternalActorSelection>;
+
+export const ExternalIdentity = z
+  .object({
+    id: z.string().uuid(),
+    accountId: z.string().uuid(),
+    source,
+    externalId,
+    subjectId: externalSubject,
+    organizationMembershipId: z.string().uuid(),
+    personalWorkspaceId: z.string().uuid(),
+    status: z.enum(["active", "disabled", "revoked"]),
+    authorizationRevision: z.number().int().positive().safe(),
+  })
+  .strict();
+export type ExternalIdentity = z.infer<typeof ExternalIdentity>;
+
+// Audit attribution, not authentication. Only the canonical access resolver
+// may establish provenance; accepting this JSON from a browser proves nothing.
+export const ExternalActorAttribution = z
+  .object({
+    accountId: z.string().uuid(),
+    authenticatingApiKeyId: z.string().uuid(),
+    externalIdentityId: z.string().uuid(),
+    externalSubjectId: externalSubject,
+    externalAuthorizationRevision: z.number().int().positive().safe(),
+    effectiveSubjectId: z.string().min(1).max(1024),
+    actingMode: z.enum(["external", "linked_native"]),
+    linkId: z.string().uuid().optional(),
+    linkRevision: z.number().int().positive().safe().optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.actingMode === "external") {
+      if (
+        value.effectiveSubjectId !== value.externalSubjectId ||
+        value.linkId !== undefined ||
+        value.linkRevision !== undefined
+      ) {
+        context.addIssue({
+          code: "custom",
+          message: "External mode cannot delegate native identity",
+        });
+      }
+    } else if (
+      !value.linkId ||
+      !value.linkRevision ||
+      !nativeSubject.safeParse(value.effectiveSubjectId).success
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Linked mode requires exact native delegation provenance",
+      });
+    }
+  });
+export type ExternalActorAttribution = z.infer<typeof ExternalActorAttribution>;
+
+/** Server-signed/encrypted continuation data, never sufficient live authority. */
+export const ExternalActorContinuation = z
+  .object({
+    identity: ExternalIdentityReference,
+    actor: ExternalActorAttribution,
+  })
+  .strict();
+export type ExternalActorContinuation = z.infer<typeof ExternalActorContinuation>;
+
+export const ExternalIdentityLink = z
+  .object({
+    id: z.string().uuid(),
+    accountId: z.string().uuid(),
+    externalIdentityId: z.string().uuid(),
+    externalIdentity: ExternalIdentityReference.optional(),
+    nativeSubjectId: nativeSubject.nullable(),
+    status: z.enum(["pending", "active", "revoked", "expired"]),
+    revision: z.number().int().positive().safe(),
+    permissions: z.array(Permission).max(Permission.options.length),
+    expiresAt: z.string().datetime({ offset: true }).nullable(),
+  })
+  .strict()
+  .refine(
+    (value) => value.status !== "active" || value.nativeSubjectId !== null,
+    "An active link requires a confirmed native identity",
+  );
+export type ExternalIdentityLink = z.infer<typeof ExternalIdentityLink>;
+
+export const ExternalIdentityLinkPage = z
+  .object({
+    links: z.array(ExternalIdentityLink).max(50),
+    nextCursor: z.string().uuid().nullable(),
+  })
+  .strict();
+export type ExternalIdentityLinkPage = z.infer<typeof ExternalIdentityLinkPage>;
+
+/** A native confirmation may narrow this request, never broaden it. The
+ * challenge is delivered once to the host and is not an authentication token. */
+export const BeginExternalIdentityLinkRequest = z
+  .object({
+    permissions: z.array(Permission).min(1).max(Permission.options.length),
+    expiresAt: z.string().datetime({ offset: true }).nullable().default(null),
+  })
+  .strict();
+export type BeginExternalIdentityLinkRequest = z.input<typeof BeginExternalIdentityLinkRequest>;
+export const ConfirmExternalIdentityLinkRequest = z
+  .object({
+    challenge: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+    expectedRevision: z.number().int().positive().safe(),
+    permissions: z.array(Permission).min(1).max(Permission.options.length),
+  })
+  .strict();
+export type ConfirmExternalIdentityLinkRequest = z.infer<typeof ConfirmExternalIdentityLinkRequest>;
+export const BeginExternalIdentityLinkResponse = z
+  .object({
+    link: ExternalIdentityLink,
+    challenge: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+    confirmBefore: z.string().datetime({ offset: true }),
+  })
+  .strict();
+export type BeginExternalIdentityLinkResponse = z.infer<typeof BeginExternalIdentityLinkResponse>;
+export const ExternalIdentityLinkPreview = z
+  .object({
+    link: ExternalIdentityLink,
+    externalIdentity: ExternalIdentityReference,
+    nativeSubjectId: nativeSubject,
+    organizationId: z.string().uuid(),
+  })
+  .strict();
+export type ExternalIdentityLinkPreview = z.infer<typeof ExternalIdentityLinkPreview>;
+
+/** Immutable accepted-work restriction, not a browser credential. Original key
+ * identity remains audit-only; durable use validates the live link and members. */
+export const ExternalLinkWorkSnapshot = z
+  .object({
+    identity: ExternalIdentityReference,
+    actor: ExternalActorAttribution.refine((value) => value.actingMode === "linked_native"),
+    permissions: z.array(Permission).max(Permission.options.length),
+    /** Absent on historical snapshots, whose legacy semantics are preserved. */
+    permissionMode: z.enum(["legacy", "explicit"]).optional(),
+  })
+  .strict();
+export type ExternalLinkWorkSnapshot = z.infer<typeof ExternalLinkWorkSnapshot>;

package/src/feedback.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const FeedbackSentiment = z.enum(["positive", "negative"]);
+export type FeedbackSentiment = z.infer<typeof FeedbackSentiment>;
+
+/** A new key means a new submission; retry the same payload with the same key. */
+export const CreateFeedbackRequest = z
+  .object({
+    idempotencyKey: z.string().uuid(),
+    sessionId: z.string().uuid().optional(),
+    turnId: z.string().uuid().optional(),
+    sentiment: FeedbackSentiment.optional(),
+    comment: z.string().max(4000).optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.turnId && !value.sessionId)
+      ctx.addIssue({ code: "custom", path: ["turnId"], message: "turnId requires sessionId" });
+    if (value.sentiment && !value.sessionId)
+      ctx.addIssue({ code: "custom", path: ["sentiment"], message: "Ratings require a session" });
+    if (!value.sentiment && !value.comment?.trim())
+      ctx.addIssue({ code: "custom", path: ["comment"], message: "Provide a rating or a comment" });
+  });
+export type CreateFeedbackRequest = z.infer<typeof CreateFeedbackRequest>;
+
+export const Feedback = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  subjectId: z.string(),
+  principalKind: z.string().nullable(),
+  sessionId: z.string().uuid().nullable(),
+  turnId: z.string().uuid().nullable(),
+  sentiment: FeedbackSentiment.nullable(),
+  comment: z.string().nullable(),
+  createdAt: z.string().datetime(),
+});
+export type Feedback = z.infer<typeof Feedback>;
+export const FeedbackSubmissionResponse = z.object({ feedback: Feedback, replayed: z.boolean() });
+export type FeedbackSubmissionResponse = z.infer<typeof FeedbackSubmissionResponse>;

package/src/github-repository-contracts.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+
+export const VerifyPublicGitHubRepositoryRefRequest = z
+  .object({
+    url: z.string().min(1).max(2048),
+    ref: z
+      .string()
+      .trim()
+      .min(1)
+      .max(1024)
+      .refine((value) => !/[\u0000-\u001f\u007f]/u.test(value), "ref contains control characters"),
+  })
+  .strict();
+export type VerifyPublicGitHubRepositoryRefRequest = z.infer<
+  typeof VerifyPublicGitHubRepositoryRefRequest
+>;
+
+export const VerifyPublicGitHubRepositoryRefResponse = z
+  .object({
+    owner: z.string().min(1).max(39),
+    name: z.string().min(1).max(100),
+    fullName: z.string().min(3).max(140),
+    canonicalUrl: z.string().url(),
+    cloneUrl: z.string().url(),
+    defaultBranch: z.string().min(1).max(1024),
+    ref: z.string().min(1).max(1024),
+    commitSha: z.string().regex(/^[0-9a-f]{40}$/u),
+  })
+  .strict();
+export type VerifyPublicGitHubRepositoryRefResponse = z.infer<
+  typeof VerifyPublicGitHubRepositoryRefResponse
+>;
+
+export const GITHUB_REPOSITORY_BRANCH_PAGE_MAX = 100 as const;
+
+export const ListGitHubRepositoryBranchesQuery = z
+  .object({
+    cursor: z.coerce.number().int().positive().max(10_000).default(1),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(GITHUB_REPOSITORY_BRANCH_PAGE_MAX)
+      .default(GITHUB_REPOSITORY_BRANCH_PAGE_MAX),
+  })
+  .strict();
+export type ListGitHubRepositoryBranchesQuery = z.infer<typeof ListGitHubRepositoryBranchesQuery>;
+
+export const GitHubRepositoryBranch = z
+  .object({
+    name: z.string().min(1).max(1024),
+    isDefault: z.boolean(),
+  })
+  .strict();
+export type GitHubRepositoryBranch = z.infer<typeof GitHubRepositoryBranch>;
+
+export const GitHubRepositoryBranchesResponse = z
+  .object({
+    branches: z.array(GitHubRepositoryBranch).max(GITHUB_REPOSITORY_BRANCH_PAGE_MAX),
+    nextCursor: z.number().int().positive().max(10_000).nullable(),
+  })
+  .strict()
+  .superRefine((response, context) => {
+    const names = new Set<string>();
+    let defaultCount = 0;
+    response.branches.forEach((branch, index) => {
+      if (names.has(branch.name)) {
+        context.addIssue({
+          code: "custom",
+          path: ["branches", index, "name"],
+          message: "branch names must be unique",
+        });
+      }
+      names.add(branch.name);
+      if (branch.isDefault) defaultCount += 1;
+    });
+    if (defaultCount > 1) {
+      context.addIssue({
+        code: "custom",
+        path: ["branches"],
+        message: "at most one branch may be marked as default",
+      });
+    }
+  });
+export type GitHubRepositoryBranchesResponse = z.infer<typeof GitHubRepositoryBranchesResponse>;

package/src/github-repository.ts

@@ -0,0 +1,59 @@
+export type CanonicalGitHubRepository = {
+  owner: string;
+  name: string;
+  fullName: string;
+  canonicalUrl: string;
+  cloneUrl: string;
+};
+
+/**
+ * Parse only a canonical public github.com repository URL. This deliberately
+ * rejects aliases, credentials, ports, query/fragment state, encoded paths,
+ * and repository subpaths so callers cannot accidentally verify one target
+ * and attach another.
+ */
+export function parseCanonicalGitHubRepositoryUrl(value: string): CanonicalGitHubRepository {
+  if (!value.startsWith("https://github.com/")) {
+    throw new Error("GitHub repository URL must use the exact https://github.com host.");
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError("GitHub repository URL is invalid.");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.hostname !== "github.com" ||
+    url.host !== "github.com" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname.includes("%")
+  ) {
+    throw new TypeError("Use a canonical https://github.com/owner/repository URL.");
+  }
+  const match = /^\/([^/]+)\/([^/]+?)\/?$/u.exec(url.pathname);
+  if (!match) {
+    throw new TypeError("GitHub repository URL must contain exactly owner/repository.");
+  }
+  const owner = match[1]!;
+  const name = match[2]!.replace(/\.git$/iu, "");
+  if (
+    !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/u.test(owner) ||
+    !/^[A-Za-z0-9_.-]{1,100}$/u.test(name) ||
+    name === "." ||
+    name === ".."
+  ) {
+    throw new TypeError("GitHub repository owner or name is invalid.");
+  }
+  const fullName = `${owner}/${name}`;
+  return {
+    owner,
+    name,
+    fullName,
+    canonicalUrl: `https://github.com/${fullName}`,
+    cloneUrl: `https://github.com/${fullName}.git`,
+  };
+}

package/src/google-drive.ts

@@ -17,9 +17,13 @@ export const GOOGLE_DRIVE_READONLY_SCOPE =
 export const GOOGLE_DRIVE_CREDENTIAL_ROLE = "google_drive_metadata" as const;
 export const GOOGLE_DRIVE_CREDENTIAL_LABEL = "Google Drive read-only source sync" as const;
 export const GOOGLE_DRIVE_LEGACY_CREDENTIAL_LABEL = "Google Drive metadata browser" as const;
+export const GOOGLE_DRIVE_PUBLICATION_SERVER_ID = "google-drive-publishing" as const;
+export const GOOGLE_DRIVE_PUBLICATION_TOOL_NAME = "google_drive_publish_file" as const;
+export const GOOGLE_DRIVE_PUBLICATION_CREATE_ACTION = "create" as const;
 
 export const GoogleDriveOAuthCapability = z.enum([
   "picker_file_read",
+  "publish_file",
   "source_metadata_discovery",
   "source_content_read",
   "recursive_source_sync",
@@ -27,7 +31,7 @@ export const GoogleDriveOAuthCapability = z.enum([
 export type GoogleDriveOAuthCapability = z.infer<typeof GoogleDriveOAuthCapability>;
 
 export type GoogleDriveOAuthScopeDecision = {
-  accessMode: "metadata_readonly" | "readonly" | null;
+  accessMode: "file_only" | "metadata_readonly" | "readonly" | null;
   capabilities: GoogleDriveOAuthCapability[];
 };
 
@@ -43,11 +47,13 @@ export function googleDriveOAuthScopeDecision(
   const granted = new Set(grantedScopes);
   const hasFullDrive = granted.has(GOOGLE_DRIVE_FULL_SCOPE);
   const hasSourceContentRead = hasFullDrive || granted.has(GOOGLE_DRIVE_READONLY_SCOPE);
+  const hasFileWrite = hasFullDrive || granted.has(GOOGLE_DRIVE_FILE_SCOPE);
   const hasSourceMetadataDiscovery =
     hasSourceContentRead || granted.has(GOOGLE_DRIVE_METADATA_READONLY_SCOPE);
-  const hasPickerFileRead = hasSourceContentRead || granted.has(GOOGLE_DRIVE_FILE_SCOPE);
+  const hasPickerFileRead = hasSourceContentRead || hasFileWrite;
   const capabilities: GoogleDriveOAuthCapability[] = [];
   if (hasPickerFileRead) capabilities.push("picker_file_read");
+  if (hasFileWrite) capabilities.push("publish_file");
   if (hasSourceMetadataDiscovery) capabilities.push("source_metadata_discovery");
   if (hasSourceContentRead) {
     capabilities.push("source_content_read", "recursive_source_sync");
@@ -57,7 +63,9 @@ export function googleDriveOAuthScopeDecision(
       ? "readonly"
       : hasSourceMetadataDiscovery
         ? "metadata_readonly"
-        : null,
+        : hasFileWrite
+          ? "file_only"
+          : null,
     capabilities,
   };
 }
@@ -148,6 +156,26 @@ export const GoogleDriveSelectedSource = z.object({
 });
 export type GoogleDriveSelectedSource = z.infer<typeof GoogleDriveSelectedSource>;
 
+export const GoogleDriveOutputDestination = z
+  .object({
+    folderId: z.string().min(1).max(256),
+    folderName: z.string().min(1).max(1024),
+    driveId: z.string().min(1).max(256).nullable(),
+    location: z.enum(["my_drive", "shared_drive"]),
+    selectedAt: z.string().datetime({ offset: true }),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if ((value.location === "my_drive") !== (value.driveId === null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["driveId"],
+        message: "Google Drive destination location does not match its drive identity",
+      });
+    }
+  });
+export type GoogleDriveOutputDestination = z.infer<typeof GoogleDriveOutputDestination>;
+
 export const GoogleDriveConnectionMetadata = z
   .object({
     credentialRole: z.literal(GOOGLE_DRIVE_CREDENTIAL_ROLE),
@@ -159,8 +187,9 @@ export const GoogleDriveConnectionMetadata = z
     googleEmail: z.string().email().max(320),
     googleDisplayName: z.string().min(1).max(512).nullable(),
     verifiedAt: z.string().datetime({ offset: true }),
-    accessMode: z.enum(["metadata_readonly", "readonly"]),
+    accessMode: z.enum(["file_only", "metadata_readonly", "readonly"]),
     lifecycle: GoogleDriveConnectionLifecycle.optional(),
+    outputDestination: GoogleDriveOutputDestination.optional(),
     documentDestination: ConnectorDocumentDestination.optional(),
     selectedSources: z.array(GoogleDriveSelectedSource).max(100).optional(),
     /** @deprecated Read `selectedSources`; retained while existing connections migrate. */
@@ -171,6 +200,7 @@ export type GoogleDriveConnectionMetadata = z.infer<typeof GoogleDriveConnection
 
 export const GoogleDriveOAuthStartRequest = z.object({
   connectionId: z.string().uuid().optional(),
+  capability: z.enum(["source_read", "publish"]).default("source_read"),
 });
 export type GoogleDriveOAuthStartRequest = z.infer<typeof GoogleDriveOAuthStartRequest>;
 
@@ -192,6 +222,48 @@ export const GoogleDriveDisconnectRequest = z.object({
 });
 export type GoogleDriveDisconnectRequest = z.infer<typeof GoogleDriveDisconnectRequest>;
 
+export const GoogleDrivePublicationExportFile = z
+  .object({
+    fileId: z.string().uuid(),
+    filename: z.string().trim().min(1).max(512),
+    contentType: z.string().trim().min(1).max(256),
+    sizeBytes: z.number().int().positive(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/u),
+    artifactId: z.string().regex(/^[0-9a-f]{32}$/u),
+    versionId: z.string().regex(/^[0-9a-f]{32}$/u),
+    materializationJobId: z.string().regex(/^[0-9a-f]{32}$/u),
+    sourceHeadSequence: z.number().int().nonnegative(),
+    sourceStateHash: z.string().regex(/^sha256:[0-9a-f]{64}$/u),
+  })
+  .strict();
+export type GoogleDrivePublicationExportFile = z.infer<typeof GoogleDrivePublicationExportFile>;
+
+export const GoogleDrivePublicationToolInput = z
+  .object({
+    title: z.string().trim().min(1).max(512),
+    modality: z.enum(["document", "spreadsheet", "presentation"]),
+    file: GoogleDrivePublicationExportFile,
+    idempotencyKey: z.string().trim().min(1).max(200),
+  })
+  .strict();
+export type GoogleDrivePublicationToolInput = z.infer<typeof GoogleDrivePublicationToolInput>;
+
+export const GoogleDrivePublicationReceipt = z
+  .object({
+    connectionId: z.string().uuid(),
+    providerFileId: z.string().min(1).max(256),
+    webViewLink: z.string().url(),
+    mimeType: z.enum([
+      "application/vnd.google-apps.document",
+      "application/vnd.google-apps.spreadsheet",
+      "application/vnd.google-apps.presentation",
+    ]),
+    destination: GoogleDriveOutputDestination,
+    replayed: z.boolean(),
+  })
+  .strict();
+export type GoogleDrivePublicationReceipt = z.infer<typeof GoogleDrivePublicationReceipt>;
+
 export const GoogleDriveBrowseItem = z.object({
   id: z.string().min(1).max(256),
   name: z.string().min(1).max(1024),