@greatwait/contracts 0.3.0 → 0.3.2

package/dist/project-notifications.js

@@ -1,6 +1,6 @@
 import { z } from "./zod.js";
 import { environmentKindSchema } from "./authority.js";
-import { callbackSigningKeyIdSchema, occurrenceIdSchema, projectIdSchema, scheduleIdSchema, } from "./identifiers.js";
+import { callbackSigningKeyIdSchema, endpointIdSchema, occurrenceIdSchema, projectIdSchema, scheduleIdSchema, } from "./identifiers.js";
 import { memberIdSchema } from "./members.js";
 import { timestampSchema } from "./time.js";
 import { pageRequestSchema, requiredIdempotencyRequestHeaderSchema, } from "./protocol.js";
@@ -23,13 +23,26 @@ export const notificationEmailSettingsSchema = z.strictObject({
     scheduleKinds: z.enum(["both", "one-shot", "recurring"]),
 });
 export const statusWebhookEventSchema = z.enum(["failed"]);
+const statusWebhookEventsSchema = z
+    .array(statusWebhookEventSchema)
+    .min(1)
+    .max(1)
+    .refine((events) => new Set(events).size === events.length, "events must be unique");
+/**
+ * The earlier configuration: a bare URL. Still accepted (W9-84): the endpoint
+ * at that URL is found or created, as endpoints.ensure does, and linked.
+ */
 export const statusWebhookConfigurationSchema = z.strictObject({
     url: z.string().url().max(2_048),
-    events: z
-        .array(statusWebhookEventSchema)
-        .min(1)
-        .max(1)
-        .refine((events) => new Set(events).size === events.length, "events must be unique"),
+    events: statusWebhookEventsSchema,
+});
+/**
+ * The status webhook's destination (W9-84): a callback endpoint in this
+ * project and environment, whose URL, headers and signing keys apply.
+ */
+export const statusWebhookEndpointConfigurationSchema = z.strictObject({
+    endpoint: endpointIdSchema,
+    events: statusWebhookEventsSchema,
 });
 export const projectNotificationSettingsSchema = z.strictObject({
     project: projectIdSchema,
@@ -38,6 +51,9 @@ export const projectNotificationSettingsSchema = z.strictObject({
     email: notificationEmailSettingsSchema,
     statusWebhook: statusWebhookConfigurationSchema
         .extend({
+        /** The destination endpoint; absent only for a URL saved before W9-84 without a key. */
+        endpoint: endpointIdSchema.optional(),
+        /** The key that signs: the endpoint's next key while one is staged, else its current one. */
         signingKey: z.strictObject({ id: callbackSigningKeyIdSchema }).optional(),
         revision: z.number().int().positive(),
     })
@@ -47,7 +63,13 @@ export const projectNotificationSettingsUpdateRequestSchema = z
     .strictObject({
     expectedRevision: z.number().int().positive(),
     email: notificationEmailSettingsSchema.optional(),
-    statusWebhook: statusWebhookConfigurationSchema.nullable().optional(),
+    statusWebhook: z
+        .union([
+        statusWebhookEndpointConfigurationSchema,
+        statusWebhookConfigurationSchema,
+    ])
+        .nullable()
+        .optional(),
 })
     .refine((request) => request.email !== undefined || request.statusWebhook !== undefined, "choose settings to change");
 export const statusSigningKeyRequestSchema = z.strictObject({
@@ -57,6 +79,11 @@ export const statusSigningKeyCreatedSchema = z.strictObject({
     settings: projectNotificationSettingsSchema,
     keyId: callbackSigningKeyIdSchema,
     secret: z.string().min(1),
+    /**
+     * Kept for compatibility (W9-84). The secret is the destination endpoint's,
+     * so a signed-in member can also reveal it on the endpoint's page, as for
+     * every endpoint secret; `shownOnce` no longer means this is the only copy.
+     */
     shownOnce: z.literal(true),
 });
 /** Safe notification payload: no customer request or response content. */
@@ -144,6 +171,8 @@ export const PROJECT_NOTIFICATION_OPERATIONS = defineOperations([
             "revision_conflict",
             "idempotency_key_reused",
             "rate_limited",
+            "scope_missing",
+            "state_conflict",
         ],
         requestHeaders: requiredIdempotencyRequestHeaderSchema,
         request: projectNotificationSettingsUpdateRequestSchema,
@@ -161,7 +190,7 @@ export const PROJECT_NOTIFICATION_OPERATIONS = defineOperations([
             : "Update delivery notification settings",
         description: globals.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "An admin updates this project's environment preferences at an expected revision. Selected recipients must be current organization members; arbitrary email addresses are not accepted. Null disables the status webhook. Changing URL or filters never reveals a signing secret. Mint the first key through the secure signing-key operation before webhook delivery starts. Failed means final unsuccessful settlement. Redelivery never repeats it. Failed-event webhook calls and their retries are free. Every failed occurrence is emailed separately; no summary window suppresses failures.",
+            : "An admin updates this project's environment preferences at an expected revision. Selected recipients must be current organization members; arbitrary email addresses are not accepted. The status webhook names its destination as `endpoint`, an enabled callback endpoint in this project and environment, which needs `endpoints:read`: failure events go to its URL with its headers, signed with its key, and delivery starts at once. A `url` instead is the earlier form: the endpoint at that address is found or created (the endpoints.ensure rules; creating needs `endpoints:write`) and linked. Without the scope a form needs, the request is refused as `scope_missing`. Null disables the status webhook. No signing secret is returned; a signed-in member reveals it on the endpoint's page. Failed means final unsuccessful settlement. Redelivery never repeats it. Failed-event webhook calls and their retries are free. Every failed occurrence is emailed separately; no summary window suppresses failures.",
     },
     {
         ...common,
@@ -172,14 +201,15 @@ export const PROJECT_NOTIFICATION_OPERATIONS = defineOperations([
         mutates: true,
         mcp: {
             kind: "unavailable",
-            reason: "Minting or rotating returns a one-time signing secret. MCP has no negotiated secure-result channel that keeps it out of ordinary tool history. Configure preferences with projectnotifications_update, then use the dashboard or an authenticated REST/SDK/CLI client for the secret.",
+            reason: "Rotating returns a signing secret, and MCP has no negotiated secure-result channel that keeps it out of ordinary tool history. Choose the status webhook's endpoint with projectnotifications_update; reveal or rotate that endpoint's key on its page in the dashboard, or with endpoints.rotateSigningKey through an authenticated REST/SDK/CLI client.",
         },
-        scopes: ["projects:administer"],
+        scopes: ["projects:administer", "endpoints:write"],
         problems: [
             ...common.problems,
             "revision_conflict",
             "state_conflict",
             "capability_not_configured",
+            "scope_missing",
         ],
         request: statusSigningKeyRequestSchema,
         requestExample: globals.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
@@ -197,6 +227,7 @@ export const PROJECT_NOTIFICATION_OPERATIONS = defineOperations([
                     statusWebhook: {
                         url: "https://hooks.example.com/status",
                         events: ["failed"],
+                        endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
                         revision: 2,
                         signingKey: { id: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
                     },
@@ -207,10 +238,10 @@ export const PROJECT_NOTIFICATION_OPERATIONS = defineOperations([
             },
         summary: globals.GREATWAIT_API_REQUEST_REGISTRY
             ? ""
-            : "Mint or rotate the status webhook signing key",
+            : "Rotate the status webhook endpoint's signing key",
         description: globals.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "An admin mints the first key or replaces the current key for an already configured status webhook at an expected revision. The secret appears only in this successful response and cannot be read back. A lost response requires a fresh revision read and another rotation. Queued deliveries using the replaced signing key are suppressed. The request is not automatically replayable; stale retries are refused. The signature covers the exact emitted body bytes.",
+            : "The earlier form, kept for existing clients: at an expected revision, rotate the signing key of the configured status webhook's endpoint exactly as endpoints.rotateSigningKey does with its default overlap. The key is the endpoint's and is shared with every schedule using it, so this also needs `endpoints:write`; without it the request is refused as `scope_missing`. A webhook saved as a bare URL is first linked to the endpoint at that address. New deliveries are signed with the new key at once, and receivers keep accepting the previous key until the overlap ends. The secret appears in this successful response and, like every endpoint secret, is also revealable by a signed-in member on the endpoint's page; `shownOnce` is kept for compatibility. The request is not automatically replayable; stale retries are refused. The signature covers the exact emitted body bytes.",
     },
     {
         ...common,

package/dist/protocol.d.ts

@@ -39,6 +39,18 @@ export type PageRequest = z.infer<typeof pageRequestSchema>;
  */
 export declare const SCHEDULE_ORDERS: readonly ["created", "due"];
 export type ScheduleOrder = (typeof SCHEDULE_ORDERS)[number];
+/**
+ * Which way a schedules listing walks its order (W9-80, FXO-3446).
+ *
+ * `asc` is what every listing has always done and keeps by default, so a
+ * client that never heard of this parameter sees nothing change. `desc` is
+ * newest-created first under `created` (the newest schedule is one row away
+ * rather than a whole book away) and latest-due first under `due`. A cursor is
+ * a position in one direction only: one issued walking `desc` is refused under
+ * `asc`, and the other way round.
+ */
+export declare const SCHEDULE_DIRECTIONS: readonly ["asc", "desc"];
+export type ScheduleDirection = (typeof SCHEDULE_DIRECTIONS)[number];
 /**
  * A schedules listing: the page, optionally one endpoint, and how to order it.
  *
@@ -58,6 +70,10 @@ export declare const scheduleListRequestSchema: import("zod").ZodObject<{
         due: "due";
         created: "created";
     }>>;
+    direction: import("zod").ZodDefault<import("zod").ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
     external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
     tag: import("zod").ZodOptional<import("zod").ZodString>;
     status: import("zod").ZodOptional<import("zod").ZodEnum<{
@@ -245,6 +261,18 @@ export type ScheduleListRequestParse = {
     readonly ok: false;
     readonly errors: readonly FieldError[];
 };
+/**
+ * Any listing request whose fields are page parameters plus string filters,
+ * read from a query string under the same rules as {@link parsePageRequest}
+ * (W9-80: the endpoints listing's filters).
+ */
+export declare function parseListingRequest<TSchema extends z.ZodTypeAny>(query: URLSearchParams, schema: TSchema): {
+    readonly ok: true;
+    readonly page: z.infer<TSchema>;
+} | {
+    readonly ok: false;
+    readonly errors: readonly FieldError[];
+};
 /** A schedules listing request: the page, and the endpoint filter if given. */
 export declare function parseScheduleListRequest(query: URLSearchParams): ScheduleListRequestParse;
 export type HistoryPageRequestParse = {

package/dist/protocol.js

@@ -16,7 +16,7 @@ import { timestampSchema } from "./time.js";
  * exactly what they were given.
  */
 export const PAGE_SIZE = PUBLIC_PAGE_SIZE;
-export const pageRequestSchema = z.object({
+export const pageRequestSchema = /* @__PURE__ */ (() => z.object({
     cursor: z.string().min(1).optional(),
     limit: z
         .number()
@@ -24,7 +24,7 @@ export const pageRequestSchema = z.object({
         .min(PAGE_SIZE.min)
         .max(PAGE_SIZE.max)
         .default(PAGE_SIZE.default),
-});
+}))();
 /**
  * A schedules listing: the page, and optionally one endpoint to keep to.
  *
@@ -43,6 +43,17 @@ export const pageRequestSchema = z.object({
  * creation instant.
  */
 export const SCHEDULE_ORDERS = ["created", "due"];
+/**
+ * Which way a schedules listing walks its order (W9-80, FXO-3446).
+ *
+ * `asc` is what every listing has always done and keeps by default, so a
+ * client that never heard of this parameter sees nothing change. `desc` is
+ * newest-created first under `created` (the newest schedule is one row away
+ * rather than a whole book away) and latest-due first under `due`. A cursor is
+ * a position in one direction only: one issued walking `desc` is refused under
+ * `asc`, and the other way round.
+ */
+export const SCHEDULE_DIRECTIONS = ["asc", "desc"];
 /**
  * A schedules listing: the page, optionally one endpoint, and how to order it.
  *
@@ -55,10 +66,14 @@ export const SCHEDULE_ORDERS = ["created", "due"];
  * a schedule with nothing on the books matches no `dueBefore`, because it has
  * no instant to compare and inventing one either way would be a guess.
  */
-export const scheduleListRequestSchema = pageRequestSchema.extend({
+export const scheduleListRequestSchema = /* @__PURE__ */ (() => pageRequestSchema.extend({
     ...scheduleSelectionSchema.shape,
     order: z.enum(SCHEDULE_ORDERS).default("created"),
-});
+    direction: z
+        .enum(SCHEDULE_DIRECTIONS)
+        .default("asc")
+        .describe("asc (default) walks the order oldest-created or soonest-due first; desc walks it newest-created or latest-due first. A cursor continues only in the direction that issued it."),
+}))();
 /**
  * Which end of a history a page walks from.
  *
@@ -70,9 +85,9 @@ export const scheduleListRequestSchema = pageRequestSchema.extend({
  */
 export const HISTORY_ORDERS = ["oldest", "newest"];
 /** A page request over a history, which may be walked from either end. */
-export const historyPageRequestSchema = pageRequestSchema.extend({
+export const historyPageRequestSchema = /* @__PURE__ */ (() => pageRequestSchema.extend({
     order: z.enum(HISTORY_ORDERS).default("oldest"),
-});
+}))();
 /**
  * A page of results.
  *
@@ -82,14 +97,14 @@ export const historyPageRequestSchema = pageRequestSchema.extend({
  * stale data as fact. `authoritative` means the answer came from the owning
  * partition; `projected` means it may lag and carries the age.
  */
-export const freshnessSchema = z.discriminatedUnion("kind", [
+export const freshnessSchema = /* @__PURE__ */ (() => z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("authoritative") }),
     z.object({
         asOf: timestampSchema,
         kind: z.literal("projected"),
         lagSeconds: z.number().int().nonnegative(),
     }),
-]);
+]))();
 /**
  * The `projected` arm alone, for a response that is never authoritative.
  *
@@ -100,11 +115,11 @@ export const freshnessSchema = z.discriminatedUnion("kind", [
  * taken, were unreachable without narrowing that no consumer could justify.
  * Naming the narrower shape moves the claim into the type.
  */
-export const projectedFreshnessSchema = z.object({
+export const projectedFreshnessSchema = /* @__PURE__ */ (() => z.object({
     asOf: timestampSchema,
     kind: z.literal("projected"),
     lagSeconds: z.number().int().nonnegative(),
-});
+}))();
 export function pageSchema(item) {
     return z.object({
         data: z.array(item),
@@ -287,6 +302,14 @@ function parametersOf(schema) {
 export function parsePageRequest(query) {
     return parseListing(query, pageRequestSchema);
 }
+/**
+ * Any listing request whose fields are page parameters plus string filters,
+ * read from a query string under the same rules as {@link parsePageRequest}
+ * (W9-80: the endpoints listing's filters).
+ */
+export function parseListingRequest(query, schema) {
+    return parseListing(query, schema);
+}
 /** A schedules listing request: the page, and the endpoint filter if given. */
 export function parseScheduleListRequest(query) {
     return parseListing(query, scheduleListRequestSchema);
@@ -337,7 +360,7 @@ function parseListing(query, schema) {
  * `version_conflict` rather than silently overwriting — a cancel racing a
  * replace must not resolve by luck.
  */
-export const versionSchema = z.number().int().positive();
+export const versionSchema = /* @__PURE__ */ (() => z.number().int().positive())();
 /**
  * A strong entity tag over a version: a quoted decimal, and nothing else.
  *
@@ -383,10 +406,10 @@ export function fromETag(etag) {
  * refinement is the extra strictness the OpenAPI preamble already discloses
  * that a described schema does not capture.
  */
-export const etagSchema = z
+export const etagSchema = /* @__PURE__ */ (() => z
     .string()
     .regex(ETAG_PATTERN, ETAG_MESSAGE)
-    .refine((value) => fromETag(value) !== undefined, ETAG_MESSAGE);
+    .refine((value) => fromETag(value) !== undefined, ETAG_MESSAGE))();
 /* -------------------------------------------------------------------------- */
 /* Idempotency                                                                */
 /* -------------------------------------------------------------------------- */
@@ -400,11 +423,11 @@ export const etagSchema = z
  * silent second write — that distinction is the whole point, and the legacy
  * scheduler had no equivalent.
  */
-export const idempotencyKeySchema = z
+export const idempotencyKeySchema = /* @__PURE__ */ (() => z
     .string()
     .min(16, "must be at least 16 characters so keys do not collide by accident")
     .max(255)
-    .regex(/^[\x20-\x7e]+$/u, "must be printable ASCII");
+    .regex(/^[\x20-\x7e]+$/u, "must be printable ASCII"))();
 /**
  * The scope a key was used in. Carried on the receipt rather than assumed,
  * because an implementation that keys its receipt store on the idempotency key
@@ -412,13 +435,13 @@ export const idempotencyKeySchema = z
  * send the same key. The scope is part of the record so that mistake cannot be
  * made silently.
  */
-export const idempotencyScopeSchema = z.object({
+export const idempotencyScopeSchema = /* @__PURE__ */ (() => z.object({
     environment: environmentIdSchema,
     operation: z.string().min(1),
     organization: organizationIdSchema,
     project: projectIdSchema,
-});
-export const idempotencyReceiptSchema = z.object({
+}))();
+export const idempotencyReceiptSchema = /* @__PURE__ */ (() => z.object({
     /**
      * Hash of the canonical request the key was first used with. Canonical
      * means: the operation name, then the request body serialized with object
@@ -431,7 +454,7 @@ export const idempotencyReceiptSchema = z.object({
     replayed: z.boolean(),
     scope: idempotencyScopeSchema,
     storedAt: timestampSchema,
-});
+}))();
 /**
  * The canonical form of a request, as the receipt's `requestFingerprint`
  * describes it: the operation name, then the body with object keys sorted and
@@ -535,9 +558,9 @@ export const CONCURRENCY_HEADERS = {
     ifMatch: "If-Match",
     replayed: "Idempotency-Replayed",
 };
-export const idempotencyRequestHeaderSchema = z.object({
+export const idempotencyRequestHeaderSchema = /* @__PURE__ */ (() => z.object({
     [CONCURRENCY_HEADERS.idempotencyKey]: idempotencyKeySchema.optional(),
-});
+}))();
 /**
  * A write for which idempotency is mandatory, rather than an optional
  * protection a caller may opt into.
@@ -547,12 +570,12 @@ export const idempotencyRequestHeaderSchema = z.object({
  * `idempotencyRequestHeaderSchema` lets schedule creation retain its published
  * optional behavior without weakening the redelivery promise.
  */
-export const requiredIdempotencyRequestHeaderSchema = z.object({
+export const requiredIdempotencyRequestHeaderSchema = /* @__PURE__ */ (() => z.object({
     [CONCURRENCY_HEADERS.idempotencyKey]: idempotencyKeySchema,
-});
-export const conditionalRequestHeaderSchema = z.object({
+}))();
+export const conditionalRequestHeaderSchema = /* @__PURE__ */ (() => z.object({
     [CONCURRENCY_HEADERS.ifMatch]: etagSchema.optional(),
-});
+}))();
 /**
  * A conditional write that refuses an unversioned request.
  *
@@ -561,18 +584,18 @@ export const conditionalRequestHeaderSchema = z.object({
  * silently accepting a missing precondition would let a stale General page
  * overwrite a newer decision.
  */
-export const requiredConditionalRequestHeaderSchema = z.object({
+export const requiredConditionalRequestHeaderSchema = /* @__PURE__ */ (() => z.object({
     [CONCURRENCY_HEADERS.ifMatch]: etagSchema,
-});
+}))();
 /**
  * Required rather than optional, deliberately: an operation that declares this
  * promises the header on every success, and a client that has to test for its
  * presence before making a conditional write will write the untested branch
  * wrong.
  */
-export const versionResponseHeaderSchema = z.object({
+export const versionResponseHeaderSchema = /* @__PURE__ */ (() => z.object({
     [CONCURRENCY_HEADERS.etag]: etagSchema,
-});
+}))();
 /**
  * What a replayed write answers with, on top of the version.
  *
@@ -588,11 +611,11 @@ export const versionResponseHeaderSchema = z.object({
  * header is the ordinary case, and a client that has to read a header to learn
  * nothing happened is a client that will not read it.
  */
-export const replayedResponseHeaderSchema = z.object({
+export const replayedResponseHeaderSchema = /* @__PURE__ */ (() => z.object({
     [CONCURRENCY_HEADERS.etag]: etagSchema,
     [CONCURRENCY_HEADERS.replayed]: z.literal("true").optional(),
-});
+}))();
 /** Replay marker for an idempotent create whose result has no ETag. */
-export const idempotencyReplayResponseHeaderSchema = z.object({
+export const idempotencyReplayResponseHeaderSchema = /* @__PURE__ */ (() => z.object({
     [CONCURRENCY_HEADERS.replayed]: z.literal("true").optional(),
-});
+}))();

package/dist/schedule-selection.js

@@ -3,7 +3,7 @@ import { endpointIdSchema, scheduleIdSchema } from "./identifiers.js";
 import { externalIdentifierSchema, scheduleTagSchema, } from "./host-correlation.js";
 import { timestampSchema } from "./time.js";
 /** Shared schedule predicates. Every populated field intersects before paging. */
-export const scheduleSelectionSchema = z.object({
+export const scheduleSelectionSchema = /* @__PURE__ */ (() => z.object({
     external_identifier: externalIdentifierSchema.optional(),
     tag: scheduleTagSchema.optional(),
     status: z.enum(["active", "paused", "cancelled", "completed"]).optional(),
@@ -18,7 +18,7 @@ export const scheduleSelectionSchema = z.object({
     schedule: scheduleIdSchema.optional(),
     dueAfter: timestampSchema.optional(),
     dueBefore: timestampSchema.optional(),
-});
+}))();
 /** Canonical predicate shape for lists, cursor bindings and bulk selections. */
 export function normalizeScheduleSelection(selection) {
     const text = selection.text?.trim();