@spacefast/common 0.0.12 → 0.0.17

package/dist/contracts/comments.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { accessRoleSchema, authorityReferenceSchema } from "./access.js";
 import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 export const commentThreadStatusSchema = z.enum(["open", "archived"]);
 export const COMMENT_SEARCH_QUERY_MAX_LENGTH = 160;
@@ -6,28 +7,147 @@ export function normalizeCommentSearchQuery(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed.slice(0, COMMENT_SEARCH_QUERY_MAX_LENGTH) : undefined;
 }
-// The space access levels capability follows (SPACEFAST-CAST-PLAN D-2). Invited
-// reviewers are space invitees with one of these levels; the on-page overlay and
-// inbox re-evaluate the effective level server-side at join — this is only the
-// stored grant the dashboard manages.
-export const collaborationReviewerLevelSchema = z.enum(["viewer", "commenter", "editor"]);
 export const COMMENT_PAGE_PATH_MAX_LENGTH = 2_048;
-// An invited reviewer: request input projected into the access lane's canonical
-// `cast_reviewer` managed block. It is never mirrored into collaboration settings.
-export const collaborationInvitedReviewerSchema = z.object({
-    email: z.string().email(),
-    level: collaborationReviewerLevelSchema,
+const COMMENT_CAPABILITIES = ["page.view", "comments.read", "comments.write"];
+export const commentCapabilitiesSchema = z
+    .array(z.enum(COMMENT_CAPABILITIES))
+    .min(2)
+    .max(3)
+    .refine((capabilities) => new Set(capabilities).size === capabilities.length, {
+    message: "comment capabilities must be unique",
+})
+    .superRefine((capabilities, context) => {
+    if (capabilities.includes("comments.write") && !capabilities.includes("comments.read")) {
+        context.addIssue({
+            code: "custom",
+            message: "comments.write requires comments.read",
+        });
+    }
+    if (capabilities.includes("comments.read") && !capabilities.includes("page.view")) {
+        context.addIssue({
+            code: "custom",
+            message: "comments.read requires page.view",
+        });
+    }
+});
+export const collaborationGuestProjectionSchema = z.object({
+    anonymousId: z.string().min(8).max(160),
+    // No control or format characters: newlines, bidi overrides, and zero-width
+    // joiners in a self-asserted display name are only ever spoofing material.
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(160)
+        .regex(/^[^\p{Cc}\p{Cf}]+$/u),
+    namedByUser: z.boolean(),
+    grantId: z.string().min(1).max(128),
+    admittedBy: z.union([
+        z.literal("anyone"),
+        z.templateLiteral(["link:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+        z.templateLiteral(["password:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+    ]),
+    emailVerified: z.boolean().default(false),
+    capabilities: commentCapabilitiesSchema,
+});
+// The identity a browser asserts when requesting a guest ticket — the
+// self-asserted subset of the guest projection.
+export const commentsGuestIdentitySchema = collaborationGuestProjectionSchema.pick({
+    anonymousId: true,
+    name: true,
+    namedByUser: true,
+});
+export function commentCapabilitiesOf(capabilities) {
+    return capabilities.filter((capability) => COMMENT_CAPABILITIES.includes(capability));
+}
+// The only account metadata exposed to Comments clients. Keep this shape
+// deliberately smaller than the private account record carried server-side.
+export const collaborationPublicProfileSchema = z
+    .object({
+    name: z.string().trim().min(1).max(120).nullable(),
+    username: z.string().trim().min(1).max(160).nullable(),
+    avatar_url: z
+        .url({ protocol: /^https?$/ })
+        .max(2_048)
+        .nullable(),
+})
+    .strict();
+export const collaborationTicketClaimsSchema = z
+    .object({
+    sub: z.string().min(1),
+    email: z.string().email().optional(),
+    profile: collaborationPublicProfileSchema.optional(),
+    role: accessRoleSchema,
+    // The session's principal, never the class of authority that admitted it:
+    // a signed-in account is "user" even when a share Link carried it in.
+    actorKind: z.enum(["user", "guest"]),
+    authorities: z.array(authorityReferenceSchema).max(16).optional(),
+    capabilities: commentCapabilitiesSchema,
+    anonymousId: z.string().min(8).max(160).optional(),
+    grantId: z.string().min(1).max(128).optional(),
+    namedByUser: z.boolean().optional(),
+    admittedBy: z
+        .union([
+        z.literal("anyone"),
+        z.templateLiteral(["link:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+        z.templateLiteral(["password:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+    ])
+        .optional(),
+    emailVerified: z.boolean().optional(),
+    room: z.string().min(1).max(4_096),
+    scope: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH),
+    surface: z.enum(["published", "preview"]),
+    nonce: z.string().min(1).max(160),
+    iat: z.number().int(),
+    nbf: z.number().int(),
+    exp: z.number().int(),
+    iss: z.literal("spacefast-api"),
+    aud: z.string().min(1),
+})
+    .superRefine((claims, context) => {
+    if (claims.actorKind !== "guest")
+        return;
+    // A guest ticket names an anonymous browser identity, and one grant always
+    // admitted it: the guest projection the mint builds carries all five of
+    // these or it is not a guest at all. Capabilities still come from the union
+    // of every authority the session holds — the admitting grant describes the
+    // admission, not the reach.
+    for (const field of [
+        "anonymousId",
+        "grantId",
+        "namedByUser",
+        "admittedBy",
+        "emailVerified",
+    ]) {
+        if (claims[field] === undefined) {
+            context.addIssue({
+                code: "custom",
+                path: [field],
+                message: `${field} is required for a guest ticket`,
+            });
+        }
+    }
+    // Identity never follows from an authority, but the reverse still holds:
+    // an anonymous principal can only ever have acquired credential-class
+    // authorities. Account-class references on a guest ticket are a forgery.
+    for (const [index, authority] of (claims.authorities ?? []).entries()) {
+        if (!authority.startsWith("link:") && !authority.startsWith("password:")) {
+            context.addIssue({
+                code: "custom",
+                path: ["authorities", index],
+                message: "a guest ticket carries only link or password authorities",
+            });
+        }
+    }
 });
 export const collaborationSettingsSchema = z
     .object({
-    anonymousReviewers: z.boolean().optional(),
-    publishedAnonymousCommenters: z.boolean().optional(),
     spamFilterEnabled: z.boolean().optional(),
-    invitedReviewers: z.array(collaborationInvitedReviewerSchema).optional(),
     // Whether comments are surfaced on the live/published host (vs preview-only).
     // The published loader (SPACEFAST-CAST-PLAN §4.2) mounts the orb on a live
     // host only when this is true; toggling it never requires a republish — the
-    // always-injected inert tag reads behavior from the ETag'd overlay-config.
+    // always-injected inert tag re-reads it through the runtime's same-origin
+    // Comments config exchange on every load.
     publishedComments: z.boolean().optional(),
     notificationPreferences: z
         .object({
@@ -39,8 +159,23 @@ export const collaborationSettingsSchema = z
         .optional(),
 })
     .strict();
+const collaborationSettingsPatchSchema = z
+    .object({
+    spamFilterEnabled: z.boolean().optional(),
+    publishedComments: z.boolean().optional(),
+    notificationPreferences: z
+        .object({
+        newThreads: z.boolean().optional(),
+        newReplies: z.boolean().optional(),
+        statusChanges: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
 export const collaborationSchema = z.object({
     spaceId: z.string(),
+    revision: z.number().int().nonnegative(),
     enabled: z.boolean(),
     castResourceId: z.string().nullable(),
     castResourceKey: z.string().nullable(),
@@ -48,17 +183,23 @@ export const collaborationSchema = z.object({
     createdAt: z.string().datetime().nullable(),
     updatedAt: z.string().datetime().nullable(),
 });
-export const collaborationUpdateSchema = z.object({
-    enabled: z.boolean(),
-    settings: collaborationSettingsSchema.optional(),
+export const collaborationUpdateSchema = z
+    .object({
+    expectedRevision: z.number().int().nonnegative(),
+    enabled: z.boolean().optional(),
+    settings: collaborationSettingsPatchSchema.optional(),
+})
+    .refine((update) => update.enabled !== undefined || update.settings !== undefined, {
+    message: "At least one collaboration field is required",
 });
-export const collaborationTokenRequestSchema = z.object({
-    versionId: z.string().min(1).optional(),
+export const commentsTicketRequestSchema = z.object({
+    spaceId: z.string().min(1),
     pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
-    anonymousId: z.string().min(1).max(160).optional(),
-    displayName: z.string().min(1).max(120).optional(),
+    origin: z.string().url(),
+    versionId: z.string().min(1).optional(),
+    identity: commentsGuestIdentitySchema.optional(),
 });
-export const collaborationTokenResponseSchema = z.object({
+export const commentsTicketResponseSchema = z.object({
     token: z.string(),
     expiresAt: z.string().datetime(),
     cast: z.object({
@@ -66,18 +207,6 @@ export const collaborationTokenResponseSchema = z.object({
         room: z.string(),
     }),
 });
-export const collaborationHandoffRequestSchema = z.object({
-    versionId: z.string().min(1),
-    pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
-});
-export const collaborationHandoffResponseSchema = z.object({
-    handoffToken: z.string(),
-    expiresAt: z.string().datetime(),
-    url: z.string().url().nullable(),
-});
-export const collaborationHandoffExchangeSchema = z.object({
-    handoffToken: z.string().min(16),
-});
 export const realtimeTokenRequestSchema = z.object({
     versionId: z.string().optional(),
     scope: z.enum(["space", "version"]).default("space"),
@@ -105,52 +234,9 @@ export const noticePublishResponseSchema = z.object({
     event: z.record(z.string(), z.unknown()).nullable(),
     broadcast: z.record(z.string(), z.unknown()).nullable(),
 });
-export const collabOverlayConfigQuerySchema = z.object({
-    path: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).optional(),
-    versionId: z.string().min(1).optional(),
-    host: z.string().min(1).optional(),
-});
-// Snake case is intentional: the injected Collab SDK consumes this alongside
-// Cast's snake-case join payload without a remapping layer.
-export const collabOverlayConfigSchema = z.object({
-    enabled: z.boolean(),
-    anonymous_commenters: z.boolean(),
-    resource_key: z.string().nullable(),
-    room_key: z.string().nullable(),
-    version: z.object({
-        id: z.string().nullable(),
-        current: z.string().nullable(),
-        // The viewed version's immutable URL; null when unknown (live context).
-        url: z.string().nullable(),
-    }),
-    // The space's canonical live/published URL; null when comments-on-live is the
-    // current context (you're already there) or no live URL exists.
-    space: z.object({
-        live_url: z.string().nullable(),
-    }),
-    ws_url: z.string().nullable(),
-    endpoints: z.object({
-        token: z.string().url(),
-        handoff_exchange: z.string().url(),
-        auth_bridge: z.string().url(),
-        screenshots: z.string().url(),
-    }),
-    features: z.object({
-        drawing: z.boolean(),
-        capture: z.boolean(),
-        notices: z.boolean(),
-    }),
-});
-// Cross-version navigation directory (§5 "versions are native"): the SDK asks
-// for the immutable URLs of the version ids present in a room's threads so
-// "Open this comment on v12" is a real link. Gated exactly like the overlay
-// config — disabled comments never leak version URLs.
+// Cross-version navigation directory: the Comments overlay asks for the
+// immutable URLs of version ids present in a room's threads.
 export const COLLAB_VERSION_URLS_MAX_IDS = 50;
-export const collabVersionUrlsQuerySchema = collabOverlayConfigQuerySchema.extend({
-    // Comma-separated version ids; the route caps the lookup at
-    // COLLAB_VERSION_URLS_MAX_IDS ids.
-    ids: z.string().min(1).max(4_096),
-});
 export const collabVersionUrlSchema = z.object({
     id: z.string(),
     url: z.string(),
@@ -162,10 +248,28 @@ export const collabVersionUrlSchema = z.object({
 export const commentAuthorSchema = z.object({
     kind: z.string().nullable(),
     id: z.string().nullable(),
+    profileId: z.string().nullable(),
     name: z.string().nullable(),
+    username: z.string().max(160).nullable(),
+    avatarUrl: z
+        .url({ protocol: /^https?$/ })
+        .max(2_048)
+        .nullable(),
     color: z.string().max(64).nullable(),
 });
 export const commentTargetSchema = z.record(z.string(), z.unknown()).nullable();
+export const commentReactionActorSchema = z.object({
+    name: z.string().nullable(),
+});
+export const commentReactionEntrySchema = z.object({
+    count: z.number().int().min(0),
+    actors: z.record(z.string(), commentReactionActorSchema),
+});
+export const COMMENT_REACTION_EMOJIS = ["👍", "❤️", "🎉", "👀", "🚀", "🙏"];
+export const commentReactionUpdateSchema = z.object({
+    emoji: z.enum(COMMENT_REACTION_EMOJIS),
+    op: z.enum(["add", "remove"]),
+});
 export const commentThreadSchema = z.object({
     id: z.string(),
     castThreadId: z.string(),
@@ -182,6 +286,7 @@ export const commentThreadSchema = z.object({
     body: z.string().nullable(),
     author: commentAuthorSchema.nullable(),
     target: commentTargetSchema,
+    reactions: z.record(z.string(), commentReactionEntrySchema),
     comments: z.array(z.record(z.string(), z.unknown())),
     permalink: z.string().nullable(),
     updatedAt: z.string().datetime().nullable(),
@@ -218,6 +323,16 @@ export const commentScreenshotSchema = z.object({
     url: z.string().url(),
     expiresAt: z.string().datetime(),
 });
+export const commentScreenshotRefreshSchema = z.object({
+    versionId: z.string().min(1),
+    pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
+    key: z.string().min(1).max(2_048),
+});
+export const commentScreenshotRefreshResponseSchema = z.object({
+    key: z.string(),
+    url: z.string().url(),
+    expiresAt: z.string().datetime(),
+});
 export const commentReplySchema = z.object({
     body: z.string().min(1).max(16_000),
     idempotencyKey: z.string().min(1).max(320).optional(),

package/dist/contracts/common.d.ts

@@ -102,19 +102,19 @@ export declare const requiredActionsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[
     type: z.ZodLiteral<"renew">;
     domainId: z.ZodString;
 }, z.core.$strip>], "type">>;
-export declare const ApiErrorResponseSchema: z.ZodObject<{
-    error: z.ZodObject<{
-        code: z.ZodString;
-        message: z.ZodString;
-        param: z.ZodOptional<z.ZodString>;
-        docsUrl: z.ZodString;
-        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        suggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        next: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        requestId: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
+export declare const ProblemDetailsSchema: z.ZodObject<{
+    type: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodNumber;
+    detail: z.ZodString;
+    code: z.ZodString;
+    pointer: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    next: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requestId: z.ZodString;
 }, z.core.$strip>;
-export type ApiErrorResponse = z.infer<typeof ApiErrorResponseSchema>;
+export type ProblemDetails = z.infer<typeof ProblemDetailsSchema>;
 export declare function dataEnvelope<T extends z.ZodType>(data: T): z.ZodObject<{
     data: T;
 }, z.core.$strip>;

package/dist/contracts/common.js

@@ -18,7 +18,7 @@ export const baseDiagnosticSchema = z.object({
     path: z
         .string()
         .nullish()
-        .describe('Artifact path the diagnostic points at, e.g. "_headers:12", when one exists.'),
+        .describe('Artifact path the diagnostic points at, for example "_headers:12", when one exists.'),
     provider: diagnosticProvider
         .nullish()
         .describe("Upstream system the diagnostic originated from, when not Spacefast itself."),
@@ -30,7 +30,7 @@ export const baseDiagnosticSchema = z.object({
     retryable: z
         .boolean()
         .nullish()
-        .describe("Whether retrying the same operation may resolve this diagnostic without the caller changing anything."),
+        .describe("Whether retrying the same operation can resolve this diagnostic without the caller changing anything."),
 });
 // Canonical DnsInstruction (internal-docs/platform.md L2500-2506): provider vocabulary
 // never leaks into `purpose`.
@@ -64,31 +64,34 @@ export const requiredActionSchema = z.discriminatedUnion("type", [
 export const requiredActionsSchema = z
     .array(requiredActionSchema)
     .describe("Concrete user steps that unblock this resource, using the one shared vocabulary.");
-// The error envelope (internal-docs/platform.md "Global API Conventions"): `docsUrl` is
-// mandatory and derived from `code` (see contracts/error-codes.ts); `param` is a
-// JSON-path-lite pointer into the failing request field on validation failures.
-export const ApiErrorResponseSchema = z.object({
-    error: z.object({
-        code: z.string().describe("Stable snake_case error code naming the failed public contract."),
-        message: z.string().describe("Human-readable failure explanation."),
-        param: z
-            .string()
-            .optional()
-            .describe('JSON-path-lite pointer into the failing request field, e.g. "files[37].path", on validation failures.'),
-        docsUrl: z
-            .string()
-            .describe("Always present; derived mechanically from `code` against the docs origin."),
-        details: AnyObjectSchema.optional().describe("Machine-readable context for the error code."),
-        suggestions: z
-            .array(z.string())
-            .optional()
-            .describe("Actionable recovery steps safe to show in dashboards, SDKs, and CLI output."),
-        next: z
-            .array(z.string())
-            .optional()
-            .describe("Copy-pasteable commands or API requests an agent can run next."),
-        requestId: z.string().optional().describe("Request id to quote when contacting support."),
-    }),
+// The error shape (internal-docs/platform.md "Global API Conventions"): every 4xx/5xx body
+// is one RFC 9457 problem details document served as `application/problem+json`. `type` and
+// `title` are derived mechanically from `code` (see contracts/error-codes.ts); `code`,
+// `pointer` (RFC 6901), `details`, `suggestions`, `next`, and `requestId` are extension members.
+export const ProblemDetailsSchema = z.object({
+    type: z
+        .string()
+        .describe("Problem type URI. It resolves to the error docs page. The server derives it mechanically from `code` against the docs origin."),
+    title: z
+        .string()
+        .describe("Short human-readable summary of the problem type. The server derives it mechanically from `code`."),
+    status: z.number().int().describe("HTTP status code of this response, repeated in the body."),
+    detail: z.string().describe("Human-readable failure explanation for this occurrence."),
+    code: z.string().describe("Stable snake_case error code naming the failed public contract."),
+    pointer: z
+        .string()
+        .optional()
+        .describe('RFC 6901 JSON Pointer into the failing request field, for example "/files/37/path", on validation failures.'),
+    details: AnyObjectSchema.optional().describe("Machine-readable context for the error code."),
+    suggestions: z
+        .array(z.string())
+        .optional()
+        .describe("Actionable recovery steps safe to show in dashboards, SDKs, and CLI output."),
+    next: z
+        .array(z.string())
+        .optional()
+        .describe("Copy-pasteable commands or API requests an agent can run next."),
+    requestId: z.string().describe("The request id to quote when contacting support."),
 });
 // Success envelope (internal-docs/platform.md "Global API Conventions"): `{ data: T }` for
 // single resources and mutations, `{ data: T[], pagination }` for lists. Mutations whose work
@@ -98,7 +101,7 @@ export function dataEnvelope(data) {
 }
 export const ApiUploadInstructionSchema = z
     .object({
-    id: z.string().describe("Upload session id (`upl_…`)."),
+    id: z.string().describe("The upload session id (`upl_…`)."),
     expiresAt: z.string().datetime(),
     method: z.literal("PUT"),
     url: z
@@ -114,7 +117,7 @@ export const CursorPaginationSchema = z.object({
     nextCursor: z
         .string()
         .nullable()
-        .describe("Opaque cursor for the next page; pass as `?cursor=`. Null on the last page."),
+        .describe("Opaque cursor for the next page; null when there are no more results."),
     hasMore: z.boolean().describe("Whether another page exists after this one."),
 });
 export const CURSOR_MAX_LENGTH = 4_096;
@@ -133,7 +136,7 @@ export const cursorListQuerySchema = z.object({
         .min(1)
         .max(CURSOR_MAX_LENGTH)
         .optional()
-        .describe("Opaque cursor from a previous page's `pagination.nextCursor`."),
+        .describe("Opaque cursor from the previous page's `nextCursor`."),
 });
 // The operator-only offset list-response shape (superadmin surfaces): the named
 // items array, plus `total`/`limit`/`offset` and the offset `pagination` block.

package/dist/contracts/continuation.js

@@ -13,7 +13,7 @@ import { AnyObjectSchema } from "./common.js";
 // generalized resume endpoint once the human step is done.
 export const RequiresActionTypeSchema = z
     .enum(["device_authorization"])
-    .describe("Stable identifier for the out-of-band step a flow is blocked on. New blocking steps are added HERE so resume stays one generalized contract.");
+    .describe("Stable identifier for the out-of-band step that blocks the flow. Add new blocking steps here so resume stays one generalized contract.");
 export const RequiresActionSchema = z
     .object({
     actionType: RequiresActionTypeSchema,
@@ -29,7 +29,7 @@ export const RequiresActionSchema = z
     continuationToken: z
         .string()
         .min(1)
-        .describe("Short-lived, single-use-on-completion, principal-scoped capability the agent presents to POST /v1/actions/resume to poll and complete this exact flow. Treat as a secret; never log it."),
+        .describe("Short-lived, principal-scoped capability for this exact flow. Present it to POST /v1/actions/resume to poll and complete the flow. The token is single-use on completion. Treat it as a secret. Never log it."),
     pollAfterSeconds: z
         .number()
         .int()
@@ -38,7 +38,7 @@ export const RequiresActionSchema = z
     expiresAt: z
         .string()
         .datetime()
-        .describe("Instant by which the human step must be completed — the originating flow's own deadline. Resume after this returns a terminal `expired` status (the token survives a short grace past this so resume can report that), but the flow can no longer be redeemed."),
+        .describe("Instant when the human step deadline is reached for the originating flow. Resume after this returns terminal `expired`. The token survives for a short grace so resume can report `expired`, but the flow can no longer be redeemed."),
 })
     .strict();
 /** The canonical `{ requiresAction }` envelope, additive alongside `{ data }` / `{ error }`. */
@@ -70,7 +70,7 @@ export const ActionResumeResponseSchema = z
         .object({
         status: z.literal("completed"),
         actionType: RequiresActionTypeSchema,
-        result: AnyObjectSchema.describe("The flow's success payload, redeemed exactly once. For device_authorization this carries the one-time `apiKey` and any `claimedSpaceId`."),
+        result: AnyObjectSchema.describe("Flow success payload, redeemed exactly once. For device_authorization, this carries the one-time `apiKey` and any `claimedSpaceId`."),
     })
         .strict(),
     z
@@ -88,4 +88,4 @@ export const ActionResumeResponseSchema = z
     })
         .strict(),
 ])
-    .describe("Consistent resume result across flows: keep polling on `pending`, read the one-time payload on `completed`, stop on `denied`/`expired`.");
+    .describe("Consistent resume result across flows. Keep polling on `pending`. Read the one-time payload on `completed`. Stop on `denied` or `expired`.");

package/dist/contracts/countries.js

@@ -1,10 +1,5 @@
-// ISO 3166-1 alpha-2 country codes — the vocabulary of the firewall card's
-// country section (contracts/access.ts `firewallCountriesSchema`, access-plan
-// §5.6). The rule `match.country` is an exact-equality matcher against the
-// edge-supplied country header, so "allow only these countries" compiles to
-// one deny/challenge rule per code in the COMPLEMENT of this list — which is
-// why the list itself is a contract: the compiler and the projection must
-// agree on the universe.
+// ISO 3166-1 alpha-2 country codes used by Grant network constraints. The
+// runtime compares them with the edge-supplied country header.
 //
 // Officially assigned codes only (no exceptionally-reserved / user-assigned
 // ranges). Display names are a UI concern (`Intl.DisplayNames`), never stored.

package/dist/contracts/data-source-routes.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare const dataSourceListItemSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"wordpress">;
+    url: z.ZodString;
+    name: z.ZodString;
+    default: z.ZodBoolean;
+}, z.core.$strict>;
+export type DataSourceListItem = z.infer<typeof dataSourceListItemSchema>;
+export declare const dataSourceListResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        dataSources: z.ZodArray<z.ZodObject<{
+            kind: z.ZodLiteral<"wordpress">;
+            url: z.ZodString;
+            name: z.ZodString;
+            default: z.ZodBoolean;
+        }, z.core.$strict>>;
+        defaultDataSource: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DataSourceListResponse = z.infer<typeof dataSourceListResponseSchema>;

package/dist/contracts/data-source-routes.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { dataEnvelope } from "./common.js";
+import { dataSourceNameSchema, wordpressDataSourceSchema } from "./space-config.js";
+export const dataSourceListItemSchema = wordpressDataSourceSchema
+    .extend({
+    name: dataSourceNameSchema,
+    default: z.boolean().describe("Whether this source is the effective default."),
+})
+    .strict();
+export const dataSourceListResponseSchema = dataEnvelope(z.object({
+    dataSources: z.array(dataSourceListItemSchema),
+    defaultDataSource: dataSourceNameSchema
+        .nullable()
+        .describe("Configured default source, or the first source in bytewise name order; null when no sources are configured."),
+}));