@opengeni/contracts 0.23.0 → 0.27.0

package/src/artifacts.ts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+
+export const WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES = 512 * 1024;
+export const WORKSPACE_ARTIFACT_TITLE_MAX_CHARS = 120;
+export const WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS = 2_000;
+export const WORKSPACE_ARTIFACT_LIST_MAX = 100;
+export const WORKSPACE_ARTIFACT_LIST_DEFAULT = 50;
+export const WORKSPACE_ARTIFACT_CURSOR_MAX_CHARS = 512;
+
+const encoder = new TextEncoder();
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/);
+
+export const WorkspaceArtifactSlug = z
+  .string()
+  .trim()
+  .min(1)
+  .max(96)
+  .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/);
+export type WorkspaceArtifactSlug = z.infer<typeof WorkspaceArtifactSlug>;
+
+export const WorkspaceArtifactStatus = z.enum(["active", "archived"]);
+export type WorkspaceArtifactStatus = z.infer<typeof WorkspaceArtifactStatus>;
+
+export const WorkspaceArtifactVersion = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  artifactId: z.string().uuid(),
+  revision: z.number().int().positive(),
+  contentType: z.literal("text/html"),
+  contentSha256: sha256,
+  sizeBytes: z.number().int().positive().max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES),
+  sourceSessionId: z.string().uuid().nullable(),
+  sourceTurnId: z.string().uuid().nullable(),
+  sourceAttemptId: z.string().uuid().nullable(),
+  sourceExecutionGeneration: z.number().int().positive().nullable(),
+  createdBySubjectId: z.string().min(1).max(1024),
+  createdAt: z.string().datetime({ offset: true }),
+});
+export type WorkspaceArtifactVersion = z.infer<typeof WorkspaceArtifactVersion>;
+
+export const WorkspaceArtifact = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  slug: WorkspaceArtifactSlug,
+  title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS),
+  description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable(),
+  status: WorkspaceArtifactStatus,
+  currentVersion: WorkspaceArtifactVersion.nullable(),
+  createdBySubjectId: z.string().min(1).max(1024),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type WorkspaceArtifact = z.infer<typeof WorkspaceArtifact>;
+
+export const WorkspaceArtifactEventType = z.enum(["published", "rolled_back"]);
+export type WorkspaceArtifactEventType = z.infer<typeof WorkspaceArtifactEventType>;
+
+export const WorkspaceArtifactEvent = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  artifactId: z.string().uuid(),
+  type: WorkspaceArtifactEventType,
+  fromVersionId: z.string().uuid().nullable(),
+  toVersionId: z.string().uuid(),
+  sourceSessionId: z.string().uuid().nullable(),
+  sourceTurnId: z.string().uuid().nullable(),
+  sourceAttemptId: z.string().uuid().nullable(),
+  sourceExecutionGeneration: z.number().int().positive().nullable(),
+  actorSubjectId: z.string().min(1).max(1024),
+  reason: z.string().min(1).max(4096),
+  createdAt: z.string().datetime({ offset: true }),
+});
+export type WorkspaceArtifactEvent = z.infer<typeof WorkspaceArtifactEvent>;
+
+export const WorkspaceArtifactListQuery = z.object({
+  limit: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(WORKSPACE_ARTIFACT_LIST_MAX)
+    .default(WORKSPACE_ARTIFACT_LIST_DEFAULT),
+  cursor: z.string().min(1).max(WORKSPACE_ARTIFACT_CURSOR_MAX_CHARS).optional(),
+});
+export type WorkspaceArtifactListQuery = z.infer<typeof WorkspaceArtifactListQuery>;
+
+export const WorkspaceArtifactListResponse = z.object({
+  artifacts: z.array(WorkspaceArtifact).max(WORKSPACE_ARTIFACT_LIST_MAX),
+  nextCursor: z.string().max(WORKSPACE_ARTIFACT_CURSOR_MAX_CHARS).nullable(),
+  truncated: z.boolean(),
+});
+export type WorkspaceArtifactListResponse = z.infer<typeof WorkspaceArtifactListResponse>;
+
+export const WorkspaceArtifactDetailResponse = z.object({
+  artifact: WorkspaceArtifact,
+  versions: z.array(WorkspaceArtifactVersion).max(WORKSPACE_ARTIFACT_LIST_MAX),
+  events: z.array(WorkspaceArtifactEvent).max(WORKSPACE_ARTIFACT_LIST_MAX),
+  versionsTruncated: z.boolean(),
+  eventsTruncated: z.boolean(),
+});
+export type WorkspaceArtifactDetailResponse = z.infer<typeof WorkspaceArtifactDetailResponse>;
+
+export const WorkspaceArtifactHtml = z
+  .string()
+  .min(1)
+  .max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES)
+  .superRefine((value, ctx) => {
+    if (encoder.encode(value).byteLength > WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES) {
+      ctx.addIssue({
+        code: "custom",
+        message: `artifact HTML exceeds ${WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES} UTF-8 bytes`,
+      });
+    }
+  });
+
+export const CreateWorkspaceArtifactRequest = z.object({
+  slug: WorkspaceArtifactSlug.optional(),
+  title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS),
+  description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
+  html: WorkspaceArtifactHtml,
+  idempotencyKey: z.string().trim().min(1).max(200),
+});
+export type CreateWorkspaceArtifactRequest = z.infer<typeof CreateWorkspaceArtifactRequest>;
+
+export const PublishWorkspaceArtifactVersionRequest = z.object({
+  title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS).optional(),
+  description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
+  html: WorkspaceArtifactHtml,
+  expectedCurrentVersionId: z.string().uuid(),
+  idempotencyKey: z.string().trim().min(1).max(200),
+});
+export type PublishWorkspaceArtifactVersionRequest = z.infer<
+  typeof PublishWorkspaceArtifactVersionRequest
+>;
+
+export const RollbackWorkspaceArtifactRequest = z.object({
+  versionId: z.string().uuid(),
+  expectedCurrentVersionId: z.string().uuid(),
+  reason: z.string().trim().min(1).max(4096),
+  idempotencyKey: z.string().trim().min(1).max(200),
+});
+export type RollbackWorkspaceArtifactRequest = z.infer<typeof RollbackWorkspaceArtifactRequest>;
+
+export const WorkspaceArtifactMutationResponse = z.object({
+  artifact: WorkspaceArtifact,
+  version: WorkspaceArtifactVersion,
+  event: WorkspaceArtifactEvent,
+  replayed: z.boolean(),
+});
+export type WorkspaceArtifactMutationResponse = z.infer<typeof WorkspaceArtifactMutationResponse>;
+
+export const WorkspaceArtifactContentResponse = z.object({
+  artifactId: z.string().uuid(),
+  versionId: z.string().uuid(),
+  contentType: z.literal("text/html"),
+  contentSha256: sha256,
+  html: WorkspaceArtifactHtml,
+});
+export type WorkspaceArtifactContentResponse = z.infer<typeof WorkspaceArtifactContentResponse>;
+
+export function normalizeWorkspaceArtifactSlug(value: string): string {
+  return value
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 96)
+    .replace(/-+$/g, "");
+}

package/src/checkpoint-provider-bindings.ts

@@ -0,0 +1,36 @@
+export type ModalCheckpointProviderBinding = {
+  version: 1;
+  serverUrl: string;
+  workspaceName: string;
+  environment: string;
+};
+
+/**
+ * One canonical, non-secret identity for the Modal namespace that owns a
+ * checkpoint. The same bytes are used for uniqueness, durable storage, and
+ * destructive-call fencing.
+ */
+export function canonicalModalCheckpointProviderBinding(
+  value: unknown,
+): { binding: ModalCheckpointProviderBinding; key: string } | null {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as Partial<ModalCheckpointProviderBinding>;
+  if (
+    candidate.version !== 1 ||
+    typeof candidate.serverUrl !== "string" ||
+    candidate.serverUrl.trim().length === 0 ||
+    typeof candidate.workspaceName !== "string" ||
+    candidate.workspaceName.trim().length === 0 ||
+    typeof candidate.environment !== "string"
+  ) {
+    return null;
+  }
+  const binding: ModalCheckpointProviderBinding = {
+    version: 1,
+    serverUrl: candidate.serverUrl,
+    workspaceName: candidate.workspaceName,
+    environment: candidate.environment,
+  };
+  const key = JSON.stringify(binding);
+  return key.length <= 1024 ? { binding, key } : null;
+}

package/src/google-drive.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+
+import { ConnectionMetadata } from "./index";
+
+export const GOOGLE_DRIVE_PROVIDER_DOMAIN = "googleapis.com" as const;
+export const GOOGLE_DRIVE_METADATA_READONLY_SCOPE =
+  "https://www.googleapis.com/auth/drive.metadata.readonly" as const;
+export const GOOGLE_DRIVE_READONLY_SCOPE =
+  "https://www.googleapis.com/auth/drive.readonly" as const;
+export const GOOGLE_DRIVE_CREDENTIAL_ROLE = "google_drive_metadata" as const;
+export const GOOGLE_DRIVE_CREDENTIAL_LABEL = "Google Drive metadata browser" as const;
+
+export const GoogleDriveTargetScope = z.enum(["user", "workspace", "organization"]);
+export type GoogleDriveTargetScope = z.infer<typeof GoogleDriveTargetScope>;
+
+export const GoogleDriveSyncCadence = z.enum(["manual", "hourly", "daily"]);
+export type GoogleDriveSyncCadence = z.infer<typeof GoogleDriveSyncCadence>;
+
+export const GoogleDriveReadPolicy = z.enum(["allow", "ask", "block"]);
+export type GoogleDriveReadPolicy = z.infer<typeof GoogleDriveReadPolicy>;
+
+export const GoogleDriveSelectedSource = z.object({
+  id: z.string().min(1).max(256),
+  name: z.string().min(1).max(1024),
+  mimeType: z.string().min(1).max(256),
+  driveId: z.string().min(1).max(256).nullable().default(null),
+  targetScope: GoogleDriveTargetScope,
+  syncCadence: GoogleDriveSyncCadence.default("hourly"),
+  readPolicy: GoogleDriveReadPolicy.default("allow"),
+  selectedAt: z.string().datetime({ offset: true }),
+});
+export type GoogleDriveSelectedSource = z.infer<typeof GoogleDriveSelectedSource>;
+
+export const GoogleDriveConnectionMetadata = z
+  .object({
+    credentialRole: z.literal(GOOGLE_DRIVE_CREDENTIAL_ROLE),
+    credentialLabel: z.literal(GOOGLE_DRIVE_CREDENTIAL_LABEL),
+    googlePermissionId: z.string().min(1).max(256),
+    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"]),
+    selectedSources: z.array(GoogleDriveSelectedSource).max(100).optional(),
+    /** @deprecated Read `selectedSources`; retained while existing connections migrate. */
+    selectedSource: GoogleDriveSelectedSource.nullable().optional(),
+  })
+  .passthrough();
+export type GoogleDriveConnectionMetadata = z.infer<typeof GoogleDriveConnectionMetadata>;
+
+export const GoogleDriveOAuthStartRequest = z.object({
+  connectionId: z.string().uuid().optional(),
+});
+export type GoogleDriveOAuthStartRequest = z.infer<typeof GoogleDriveOAuthStartRequest>;
+
+export const GoogleDriveOAuthStartResponse = z.object({
+  authorizationUrl: z.string().url(),
+  expiresAt: z.string().datetime({ offset: true }),
+});
+export type GoogleDriveOAuthStartResponse = z.infer<typeof GoogleDriveOAuthStartResponse>;
+
+export const GoogleDriveBrowseItem = z.object({
+  id: z.string().min(1).max(256),
+  name: z.string().min(1).max(1024),
+  mimeType: z.string().min(1).max(256),
+  kind: z.enum(["folder", "file"]),
+  driveId: z.string().min(1).max(256).nullable(),
+  modifiedTime: z.string().datetime({ offset: true }).nullable(),
+  size: z.string().regex(/^\d+$/).nullable(),
+  webViewLink: z.string().url().nullable(),
+});
+export type GoogleDriveBrowseItem = z.infer<typeof GoogleDriveBrowseItem>;
+
+export const GoogleDriveBrowseResponse = z.object({
+  connection: z.lazy(() => ConnectionMetadata),
+  parentId: z.string().min(1).max(256),
+  current: GoogleDriveBrowseItem.nullable(),
+  items: z.array(GoogleDriveBrowseItem),
+  nextPageToken: z.string().min(1).max(4096).nullable(),
+  incompleteSearch: z.boolean(),
+});
+export type GoogleDriveBrowseResponse = z.infer<typeof GoogleDriveBrowseResponse>;
+
+export const SaveGoogleDriveSourceRequest = z.object({
+  sources: z
+    .array(
+      GoogleDriveBrowseItem.pick({
+        id: true,
+        name: true,
+        mimeType: true,
+        driveId: true,
+      }),
+    )
+    .max(100)
+    .refine((sources) => new Set(sources.map((source) => source.id)).size === sources.length, {
+      message: "Google Drive sources must be unique",
+    }),
+  targetScope: GoogleDriveTargetScope,
+  syncCadence: GoogleDriveSyncCadence.default("hourly"),
+  readPolicy: GoogleDriveReadPolicy.default("allow"),
+});
+export type SaveGoogleDriveSourceRequest = z.infer<typeof SaveGoogleDriveSourceRequest>;