@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/site-data.ts

@@ -0,0 +1,339 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/**
+ * Site Data: persistent JSON collections and files that belong to a
+ * published Site. Shared by the HTTP API, first-party agent tools and the SDK.
+ */
+
+export const SiteDataAccessMode = /* @__PURE__ */ defineSchema(() =>
+  z
+    .enum(["shared", "shared_read", "per_viewer", "append_only"])
+    .describe(
+      "shared: viewers read and write every record. shared_read: viewers read, only managers write. per_viewer: each viewer reads and writes only their own records. append_only: viewers add records and read only their own.",
+    ),
+);
+export type SiteDataAccessMode = z.infer<typeof SiteDataAccessMode>;
+
+/** What anonymous guests of a public published Site may do in a collection. */
+export const SiteDataGuestAccess = /* @__PURE__ */ defineSchema(() =>
+  z
+    .enum(["none", "read", "append", "own"])
+    .describe(
+      "Published Sites only: what anonymous guests may do. none (default): nothing. read: read what viewers read. append: add records and read their own. own: add, read, change and delete their own.",
+    ),
+);
+export type SiteDataGuestAccess = z.infer<typeof SiteDataGuestAccess>;
+
+const CollectionName = z
+  .string()
+  .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/)
+  .describe("Collection name: a letter, then letters, digits, - or _ (up to 64).");
+const FieldPath = z
+  .string()
+  .min(1)
+  .max(300)
+  .describe(
+    "A data field as a dotted path (up to 4 levels), or a system field: $id, $key, $owner, $createdAt, $updatedAt, $version.",
+  );
+const RecordKey = z.string().min(1).max(256).describe("Your own stable record key.");
+const Scalar = z.union([z.string().max(1024), z.number(), z.boolean(), z.null()]);
+const RecordData = z
+  .record(z.string(), z.unknown())
+  .describe("The record's JSON object (at most 256 KB by default).");
+
+export const SiteDataFilter = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    field: FieldPath,
+    op: z
+      .enum(["eq", "ne", "in", "gt", "gte", "lt", "lte", "contains", "exists"])
+      .describe(
+        "contains matches an array element or a case-insensitive substring; exists takes true or false.",
+      ),
+    value: z
+      .union([Scalar, z.array(Scalar).max(100)])
+      .optional()
+      .describe("The value to compare with; an array for in. $owner accepts me."),
+  }),
+);
+export type SiteDataFilter = z.infer<typeof SiteDataFilter>;
+
+export const SiteDataSort = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    field: FieldPath,
+    direction: z.enum(["asc", "desc"]).optional().describe("Defaults to asc."),
+  }),
+);
+export type SiteDataSort = z.infer<typeof SiteDataSort>;
+
+export const SiteDataQueryRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    collection: CollectionName,
+    where: z.array(SiteDataFilter).max(20).optional().describe("All filters must match."),
+    sort: z
+      .array(SiteDataSort)
+      .max(2)
+      .optional()
+      .describe("Up to two sort keys. Defaults to newest first."),
+    limit: z.number().int().min(1).max(200).optional().describe("Page size, 50 by default."),
+    cursor: z.string().max(4096).nullable().optional().describe("nextCursor from the last page."),
+    count: z.boolean().optional().describe("Also return the total number of matches."),
+    scope: z
+      .enum(["own", "all"])
+      .optional()
+      .describe("own returns only the caller's records; all returns every readable record."),
+  }),
+);
+export type SiteDataQueryRequest = z.infer<typeof SiteDataQueryRequest>;
+
+export const SiteDataGetRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      collection: CollectionName,
+      id: z.string().uuid().optional().describe("Record id."),
+      key: RecordKey.optional(),
+    })
+    .refine((value) => (value.id === undefined) !== (value.key === undefined), {
+      message: "Give exactly one of id or key",
+    }),
+);
+export type SiteDataGetRequest = z.infer<typeof SiteDataGetRequest>;
+
+const RecordRef = {
+  id: z.string().uuid().optional().describe("Record id; give id or key."),
+  key: RecordKey.optional(),
+};
+const ExpectedVersion = z
+  .number()
+  .int()
+  .min(0)
+  .optional()
+  .describe("Fail with a conflict unless the record has this version (0: must not exist).");
+
+export const SiteDataWriteOperation = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("op", [
+    z.object({
+      op: z.literal("insert"),
+      collection: CollectionName,
+      key: RecordKey.optional(),
+      data: RecordData,
+    }),
+    z.object({
+      op: z.literal("put").describe("Create or replace the record with this key."),
+      collection: CollectionName,
+      key: RecordKey,
+      data: RecordData,
+      expectedVersion: ExpectedVersion,
+    }),
+    z.object({
+      op: z.literal("patch").describe("Shallow-merge data into the record."),
+      collection: CollectionName,
+      ...RecordRef,
+      data: RecordData,
+      expectedVersion: ExpectedVersion,
+    }),
+    z.object({
+      op: z.literal("delete"),
+      collection: CollectionName,
+      ...RecordRef,
+      expectedVersion: ExpectedVersion,
+    }),
+    z.object({
+      op: z.literal("increment").describe("Atomically add to a numeric field."),
+      collection: CollectionName,
+      ...RecordRef,
+      field: FieldPath,
+      by: z.number().optional().describe("Amount to add, 1 by default."),
+    }),
+  ]),
+);
+export type SiteDataWriteOperation = z.infer<typeof SiteDataWriteOperation>;
+
+export const SiteDataWriteRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    operations: z
+      .array(SiteDataWriteOperation)
+      .min(1)
+      .max(100)
+      .describe("Up to 100 operations, applied together or not at all."),
+  }),
+);
+export type SiteDataWriteRequest = z.infer<typeof SiteDataWriteRequest>;
+
+export const SiteDataCollectionDefinitionRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    accessMode: SiteDataAccessMode,
+    privateRecords: z
+      .boolean()
+      .optional()
+      .describe("per_viewer only: keep records private even from the Site's managers."),
+    guestAccess: SiteDataGuestAccess.optional().describe(
+      "Anonymous guests of a public published Site; omitted keeps the current rule (none for a new collection).",
+    ),
+    jsonSchema: z
+      .record(z.string(), z.unknown())
+      .nullable()
+      .optional()
+      .describe("Optional JSON Schema every written record must match."),
+    indexedFields: z
+      .array(z.string().min(1).max(300).describe("Dotted data path."))
+      .max(10)
+      .optional()
+      .describe("Fields to index for faster numeric range filters."),
+    uniqueFields: z
+      .array(
+        z
+          .array(z.string().min(1).max(300).describe("Dotted data path."))
+          .min(1)
+          .max(4)
+          .describe("A set of fields whose combined value must be unique."),
+      )
+      .max(5)
+      .optional()
+      .describe("Unique field sets. Per-viewer collections enforce them per viewer."),
+  }),
+);
+export type SiteDataCollectionDefinitionRequest = z.infer<
+  typeof SiteDataCollectionDefinitionRequest
+>;
+
+export const SiteDataConfirmRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({ confirm: z.literal(true).describe("Must be true.") }),
+);
+
+export const SiteDataImportRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      format: z.enum(["json", "csv"]),
+      records: z
+        .array(RecordData)
+        .max(1000)
+        .optional()
+        .describe("JSON format: the records to import."),
+      csv: z
+        .string()
+        .max(2 * 1024 * 1024)
+        .optional()
+        .describe("CSV format: a header row, then one record per row. Values import as text."),
+      keyField: z
+        .string()
+        .min(1)
+        .max(300)
+        .optional()
+        .describe("Use this field as each record's key, so re-importing replaces records."),
+    })
+    .refine((value) => (value.format === "json" ? !!value.records : value.csv !== undefined), {
+      message: "Give records for json or csv for csv",
+    }),
+);
+export type SiteDataImportRequest = z.infer<typeof SiteDataImportRequest>;
+
+export const SiteDataFileScope = /* @__PURE__ */ defineSchema(() =>
+  z
+    .enum(["shared", "private"])
+    .describe("shared: every viewer can open it. private: only the uploader and managers."),
+);
+export type SiteDataFileScope = z.infer<typeof SiteDataFileScope>;
+
+export const SiteDataErrorCode = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["validation", "conflict", "not_found", "forbidden", "quota_exceeded", "rate_limited"]),
+);
+export type SiteDataErrorCode = z.infer<typeof SiteDataErrorCode>;
+
+/** HTTP status for each Site Data error code. */
+export const SITE_DATA_ERROR_STATUS: Record<SiteDataErrorCode, number> = {
+  validation: 422,
+  conflict: 409,
+  not_found: 404,
+  forbidden: 403,
+  quota_exceeded: 413,
+  rate_limited: 429,
+};
+
+export type SiteDataRecordResponse = {
+  id: string;
+  key: string | null;
+  data: Record<string, unknown>;
+  owner: string;
+  createdBy: string;
+  updatedBy: string;
+  version: number;
+  sizeBytes: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type SiteDataCollectionResponse = {
+  id: string;
+  name: string;
+  accessMode: SiteDataAccessMode;
+  privateRecords: boolean;
+  guestAccess: SiteDataGuestAccess;
+  jsonSchema: Record<string, unknown> | null;
+  indexedFields: string[];
+  uniqueFields: string[][];
+  recordCount: number;
+  recordBytes: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type SiteDataLimitsResponse = {
+  recordBytesPerSite: number;
+  maxRecordBytes: number;
+  maxCollectionsPerSite: number;
+  fileBytesPerSite: number;
+  maxFileBytes: number;
+  workspaceBytes: number;
+};
+
+export type SiteDataDescribeResponse = {
+  siteId: string;
+  collections: SiteDataCollectionResponse[];
+  usage: {
+    collectionCount: number;
+    recordCount: number;
+    recordBytes: number;
+    fileCount: number;
+    fileBytes: number;
+    workspaceBytes: number;
+  };
+  limits: SiteDataLimitsResponse;
+};
+
+export type SiteDataFileResponse = {
+  id: string;
+  name: string;
+  contentType: string;
+  sizeBytes: number;
+  sha256: string;
+  scope: SiteDataFileScope;
+  owner: string;
+  createdBy: string;
+  createdAt: string;
+};
+
+export type SiteDataQueryResponse = {
+  records: SiteDataRecordResponse[];
+  nextCursor: string | null;
+  count?: number;
+};
+
+export type SiteDataWriteResultResponse =
+  | { op: "insert" | "put" | "patch" | "increment"; record: SiteDataRecordResponse }
+  | { op: "delete"; deleted: { id: string } };
+
+export type SiteDataWriteResponse = { results: SiteDataWriteResultResponse[] };
+
+export type SiteDataImportResponse = { imported: number };
+
+export type SiteDataFileListResponse = {
+  files: SiteDataFileResponse[];
+  nextCursor: string | null;
+};
+
+export type SiteDataFileUrlResponse = {
+  url: string;
+  expiresAt: string;
+  file: SiteDataFileResponse;
+};

package/src/site-operations.ts

@@ -0,0 +1,154 @@
+// Zod-free on purpose: browser bundles (the Site runtime, the console Site
+// bridge and the gateway shell) import this module, and must not pull in zod.
+
+// ---------------------------------------------------------------------------
+// Site operation allowlist
+// ---------------------------------------------------------------------------
+
+/**
+ * Every HTTP operation Site code may perform through a host, as an explicit
+ * allowlist (method + exact path shape) rather than a URL prefix. Paths are
+ * the suffix after `/v1/workspaces/site-host` that the in-Site SDK client
+ * uses; `/v1/config/client` is the one path outside that prefix.
+ *
+ * The console host forwards an allowed operation to the ordinary workspace
+ * route with Site provenance. The gateway forwards it to `/_og/api<suffix>`
+ * and the API serves it at `/v1/site-runtime<suffix>`. `agent: true` marks
+ * operations that start or message an agent; every such route records which
+ * Site (and version) originated it.
+ */
+export type SiteOperationMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type SiteOperation = {
+  id: string;
+  method: SiteOperationMethod;
+  /** Anchored pattern on the site-host suffix (`""` is the workspace itself). */
+  pattern: RegExp;
+  agent?: true;
+  stream?: true;
+};
+
+const ID = "[A-Za-z0-9_-]{1,128}";
+const DATA = "/published-artifacts/current/(?:data|files)(?:/[A-Za-z0-9._~:@!$&'()*+,;=-]+)*";
+
+export const SITE_OPERATIONS: readonly SiteOperation[] = Object.freeze([
+  { id: "config.client", method: "GET", pattern: /^\/v1\/config\/client$/u },
+  { id: "workspace.get", method: "GET", pattern: /^$/u },
+  { id: "site.config", method: "GET", pattern: /^\/site\/config$/u },
+  { id: "models.list", method: "GET", pattern: /^\/model-catalog$/u },
+  { id: "sessions.list", method: "GET", pattern: /^\/sessions$/u },
+  { id: "sessions.create", method: "POST", pattern: /^\/sessions$/u, agent: true },
+  { id: "sessions.get", method: "GET", pattern: new RegExp(`^/sessions/${ID}$`, "u") },
+  { id: "sessions.events", method: "GET", pattern: new RegExp(`^/sessions/${ID}/events$`, "u") },
+  {
+    id: "sessions.stream",
+    method: "GET",
+    pattern: new RegExp(`^/sessions/${ID}/events/stream$`, "u"),
+    stream: true,
+  },
+  {
+    id: "sessions.send",
+    method: "POST",
+    pattern: new RegExp(`^/sessions/${ID}/events$`, "u"),
+    agent: true,
+  },
+  {
+    id: "sessions.steer",
+    method: "POST",
+    pattern: new RegExp(`^/sessions/${ID}/steer$`, "u"),
+    agent: true,
+  },
+  {
+    id: "sessions.control",
+    method: "POST",
+    pattern: new RegExp(`^/sessions/${ID}/control$`, "u"),
+    agent: true,
+  },
+  { id: "sessions.queue", method: "GET", pattern: new RegExp(`^/sessions/${ID}/queue$`, "u") },
+  // SessionConversation's documented queue edit/delete/steer/move.
+  {
+    id: "sessions.queue.item",
+    method: "POST",
+    pattern: new RegExp(`^/sessions/${ID}/queue/${ID}/(?:move|edit|steer|delete)$`, "u"),
+    agent: true,
+  },
+  // SessionConversation's durable composer draft and its Send.
+  {
+    id: "sessions.composerDraft.get",
+    method: "GET",
+    pattern: new RegExp(`^/sessions/${ID}/composer-draft$`, "u"),
+  },
+  {
+    id: "sessions.composerDraft.put",
+    method: "PUT",
+    pattern: new RegExp(`^/sessions/${ID}/composer-draft$`, "u"),
+  },
+  {
+    id: "sessions.composerDraft.submit",
+    method: "POST",
+    pattern: new RegExp(`^/sessions/${ID}/composer-draft/submit$`, "u"),
+    agent: true,
+  },
+  {
+    id: "sessions.humanInput",
+    method: "GET",
+    pattern: new RegExp(`^/sessions/${ID}/human-input-requests$`, "u"),
+  },
+  // SessionConversation's human-input form reads the one open request.
+  {
+    id: "sessions.humanInput.get",
+    method: "GET",
+    pattern: new RegExp(`^/sessions/${ID}/human-input-requests/${ID}$`, "u"),
+  },
+  { id: "data.read", method: "GET", pattern: new RegExp(`^${DATA}$`, "u") },
+  { id: "data.write", method: "POST", pattern: new RegExp(`^${DATA}$`, "u") },
+  { id: "data.put", method: "PUT", pattern: new RegExp(`^${DATA}$`, "u") },
+  { id: "data.patch", method: "PATCH", pattern: new RegExp(`^${DATA}$`, "u") },
+  { id: "data.delete", method: "DELETE", pattern: new RegExp(`^${DATA}$`, "u") },
+  // Site SQL (PR B): run one named query the owner defined; never raw SQL.
+  {
+    id: "sql.run",
+    method: "POST",
+    pattern: /^\/published-artifacts\/current\/sql\/queries\/[A-Za-z][A-Za-z0-9_-]{0,63}$/u,
+  },
+  { id: "site.report", method: "POST", pattern: /^\/site\/reports$/u },
+] satisfies SiteOperation[]);
+
+/**
+ * Tool bridge methods (MessagePort, not HTTP). The gateway serves them at
+ * POST /_og/api/tools/<method>; the console uses its tool gateway client.
+ */
+export const SITE_TOOL_METHODS = Object.freeze([
+  "catalog",
+  "declarations",
+  "call",
+  "resolve",
+  "invoke",
+] as const);
+export type SiteToolMethod = (typeof SITE_TOOL_METHODS)[number];
+
+const SITE_HOST_PREFIX = "/v1/workspaces/site-host";
+
+/**
+ * Match a Site-originated request against the allowlist. `path` is the
+ * pathname the in-Site SDK used (`/v1/workspaces/site-host/...` or
+ * `/v1/config/client`), without query. Returns the operation and the
+ * site-host suffix, or null when the operation is not allowed. Refuses
+ * encoded separators, dot segments and control characters.
+ */
+export function matchSiteOperation(
+  method: string,
+  path: string,
+): { operation: SiteOperation; suffix: string } | null {
+  if (/[%\\#\u0000-\u0020\u007f]/u.test(path)) return null;
+  if (path.split("/").some((part) => part === "." || part === "..")) return null;
+  const upper = method.toUpperCase();
+  let suffix: string;
+  if (path === "/v1/config/client") suffix = path;
+  else if (path === SITE_HOST_PREFIX) suffix = "";
+  else if (path.startsWith(`${SITE_HOST_PREFIX}/`)) suffix = path.slice(SITE_HOST_PREFIX.length);
+  else return null;
+  const operation = SITE_OPERATIONS.find(
+    (candidate) => candidate.method === upper && candidate.pattern.test(suffix),
+  );
+  return operation ? { operation, suffix } : null;
+}