@greatwait/contracts 0.2.2 → 0.3.0

package/dist/operations.js

@@ -1,3 +1,5 @@
+import { projectAttemptPageSchema, projectAttemptSearchRequestSchema, } from "./attempt-search.js";
+import { BULK_API_OPERATIONS } from "./bulk-operations.js";
 import { effectiveCustomerLimitsSchema } from "./effective-limits.js";
 import { z } from "./zod.js";
 import { MEMBER_OPERATIONS } from "./members.js";
@@ -545,6 +547,7 @@ export const OPERATIONS = [
         surfaces: ["api", "mock"],
     },
     ...DATA_EXPORT_OPERATIONS,
+    ...BULK_API_OPERATIONS,
     ...MEMBER_OPERATIONS,
     ...PROJECT_NOTIFICATION_OPERATIONS,
     ...ORGANIZATION_LIFECYCLE_OPERATIONS,
@@ -3622,6 +3625,70 @@ export const OPERATIONS = [
             : "Read an occurrence",
         surfaces: ["api", "mock"],
     },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Search all retained delivery attempts by actual startedAt in the required UTC interval [startedFrom, startedBefore), newest first with attempt ID breaking ties. Combine HTTP responseStatus, statusClass, attempt outcome or diagnostic, endpoint, schedule and exact host identifier/tag filters. The matched attempt outcome remains searchable after recovery; occurrence.state is its current outcome. Follow schedule and occurrence IDs to retained details and attempts.list for the complete retry chain. Only safe metadata is returned. Retention horizons describe normal plan history and attempt-detail limits; absence after expiry is not evidence that a delivery never happened. Unavailable queries fail explicitly. Cursors are bound to the verified authority and every selected filter.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                data: [
+                    {
+                        attempt: {
+                            id: "att_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                            attemptNumber: 1,
+                            occurrence: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                            startedAt: "2026-07-28T15:00:00.000Z",
+                            classifiedAt: "2026-07-28T15:00:00.071Z",
+                            state: "retryable_failure",
+                            responseStatus: 503,
+                            durationMs: 71,
+                            diagnostic: "http_retryable",
+                            remediation: "review_retry_policy",
+                            trigger: { kind: "automatic" },
+                        },
+                        occurrence: {
+                            id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                            schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                            generation: 1,
+                            sequence: 1,
+                            attemptCount: 2,
+                            plannedFor: "2026-07-28T14:50:00.000Z",
+                            settledAt: "2026-07-28T15:00:04.000Z",
+                            state: "succeeded",
+                        },
+                        schedule: {
+                            id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                            name: "Recovered delivery",
+                        },
+                    },
+                ],
+                freshness: { kind: "authoritative" },
+                retention: {
+                    from: "2026-07-21T15:00:00.000Z",
+                    detailsFrom: "2026-07-21T15:00:00.000Z",
+                },
+            },
+        id: "attempts.search",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/attempts",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request"],
+        query: projectAttemptSearchRequestSchema,
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : projectAttemptPageSchema,
+        scopes: ["occurrences:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Search delivery attempts by actual time",
+        surfaces: ["api", "mock"],
+    },
     {
         creates: false,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY

package/dist/protocol.d.ts

@@ -54,14 +54,28 @@ export type ScheduleOrder = (typeof SCHEDULE_ORDERS)[number];
 export declare const scheduleListRequestSchema: import("zod").ZodObject<{
     cursor: import("zod").ZodOptional<import("zod").ZodString>;
     limit: import("zod").ZodDefault<import("zod").ZodNumber>;
-    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
-    tag: import("zod").ZodOptional<import("zod").ZodString>;
-    dueBefore: import("zod").ZodOptional<import("zod").ZodString>;
-    endpoint: import("zod").ZodOptional<import("zod").ZodString>;
     order: import("zod").ZodDefault<import("zod").ZodEnum<{
-        created: "created";
         due: "due";
+        created: "created";
     }>>;
+    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    tag: import("zod").ZodOptional<import("zod").ZodString>;
+    status: import("zod").ZodOptional<import("zod").ZodEnum<{
+        cancelled: "cancelled";
+        active: "active";
+        paused: "paused";
+        completed: "completed";
+    }>>;
+    recurrence: import("zod").ZodOptional<import("zod").ZodEnum<{
+        at: "at";
+        every: "every";
+        cron: "cron";
+    }>>;
+    endpoint: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodLiteral<"none">]>>;
+    text: import("zod").ZodOptional<import("zod").ZodString>;
+    schedule: import("zod").ZodOptional<import("zod").ZodString>;
+    dueAfter: import("zod").ZodOptional<import("zod").ZodString>;
+    dueBefore: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$strip>;
 export type ScheduleListRequest = z.infer<typeof scheduleListRequestSchema>;
 /**

package/dist/protocol.js

@@ -1,7 +1,7 @@
 import { z } from "./zod.js";
-import { externalIdentifierSchema, scheduleTagSchema, } from "./host-correlation.js";
+import { scheduleSelectionSchema } from "./schedule-selection.js";
 import { PUBLIC_PAGE_SIZE } from "./configuration-bounds.js";
-import { endpointIdSchema, environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
+import { environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
 import { timestampSchema } from "./time.js";
 /**
  * Request and collection mechanics: paging, optimistic concurrency, and
@@ -56,10 +56,7 @@ export const SCHEDULE_ORDERS = ["created", "due"];
  * no instant to compare and inventing one either way would be a guess.
  */
 export const scheduleListRequestSchema = pageRequestSchema.extend({
-    external_identifier: externalIdentifierSchema.optional(),
-    tag: scheduleTagSchema.optional(),
-    dueBefore: timestampSchema.optional(),
-    endpoint: endpointIdSchema.optional(),
+    ...scheduleSelectionSchema.shape,
     order: z.enum(SCHEDULE_ORDERS).default("created"),
 });
 /**
@@ -160,7 +157,17 @@ function authorityFingerprint(authority) {
     return hash.toString(16).padStart(8, "0");
 }
 function base64UrlEncode(value) {
-    return btoa(value)
+    // Cursor JSON can include Unicode filter values. Escape UTF-16 units outside
+    // Latin-1 before btoa; JSON.parse restores them, including surrogate pairs.
+    // Keep the existing decoder so previously issued Latin-1 cursors still work.
+    const encodable = value
+        .split("")
+        .map((unit) => {
+        const code = unit.charCodeAt(0);
+        return code > 255 ? `\\u${code.toString(16).padStart(4, "0")}` : unit;
+    })
+        .join("");
+    return btoa(encodable)
         .replace(/\+/gu, "-")
         .replace(/\//gu, "_")
         .replace(/=+$/u, "");

package/dist/schedule-selection.d.ts

@@ -0,0 +1,28 @@
+import { z } from "./zod.js";
+/** Shared schedule predicates. Every populated field intersects before paging. */
+export declare const scheduleSelectionSchema: import("zod").ZodObject<{
+    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    tag: import("zod").ZodOptional<import("zod").ZodString>;
+    status: import("zod").ZodOptional<import("zod").ZodEnum<{
+        cancelled: "cancelled";
+        active: "active";
+        paused: "paused";
+        completed: "completed";
+    }>>;
+    recurrence: import("zod").ZodOptional<import("zod").ZodEnum<{
+        at: "at";
+        every: "every";
+        cron: "cron";
+    }>>;
+    endpoint: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodLiteral<"none">]>>;
+    text: import("zod").ZodOptional<import("zod").ZodString>;
+    schedule: import("zod").ZodOptional<import("zod").ZodString>;
+    dueAfter: import("zod").ZodOptional<import("zod").ZodString>;
+    dueBefore: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export type ScheduleSelection = z.infer<typeof scheduleSelectionSchema>;
+export type NormalizedScheduleSelection = {
+    readonly [Key in keyof ScheduleSelection]?: Exclude<ScheduleSelection[Key], undefined>;
+};
+/** Canonical predicate shape for lists, cursor bindings and bulk selections. */
+export declare function normalizeScheduleSelection(selection: ScheduleSelection): NormalizedScheduleSelection;

package/dist/schedule-selection.js

@@ -0,0 +1,48 @@
+import { z } from "./zod.js";
+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({
+    external_identifier: externalIdentifierSchema.optional(),
+    tag: scheduleTagSchema.optional(),
+    status: z.enum(["active", "paused", "cancelled", "completed"]).optional(),
+    recurrence: z.enum(["at", "every", "cron"]).optional(),
+    endpoint: z.union([endpointIdSchema, z.literal("none")]).optional(),
+    text: z
+        .string()
+        .max(256)
+        .refine((value) => !value.includes("\u0000"), "must not contain NUL characters")
+        .optional()
+        .describe("Case-insensitive literal substring of schedule name, endpoint address or schedule identifier."),
+    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();
+    return {
+        ...(selection.external_identifier === undefined
+            ? {}
+            : { external_identifier: selection.external_identifier }),
+        ...(selection.tag === undefined ? {} : { tag: selection.tag }),
+        ...(selection.status === undefined ? {} : { status: selection.status }),
+        ...(selection.recurrence === undefined
+            ? {}
+            : { recurrence: selection.recurrence }),
+        ...(selection.endpoint === undefined
+            ? {}
+            : { endpoint: selection.endpoint }),
+        ...(text === undefined || text === "" ? {} : { text }),
+        ...(selection.schedule === undefined
+            ? {}
+            : { schedule: selection.schedule }),
+        ...(selection.dueAfter === undefined
+            ? {}
+            : { dueAfter: selection.dueAfter }),
+        ...(selection.dueBefore === undefined
+            ? {}
+            : { dueBefore: selection.dueBefore }),
+    };
+}

package/dist/scheduling-records.d.ts

@@ -7,9 +7,9 @@ export declare const portableScheduleRecordSchema: import("zod").ZodObject<{
             GET: "GET";
         }>;
         bodyMode: import("zod").ZodEnum<{
+            none: "none";
             envelope: "envelope";
             json: "json";
-            none: "none";
         }>;
         headers: import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
             name: import("zod").ZodString;
@@ -132,9 +132,9 @@ export declare const portableScheduleRecordSchema: import("zod").ZodObject<{
         timeZone: import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<string, string>>;
     }, import("zod/v4/core").$strip>], "kind">;
     status: import("zod").ZodEnum<{
-        paused: "paused";
-        active: "active";
         cancelled: "cancelled";
+        active: "active";
+        paused: "paused";
         completed: "completed";
     }>;
     updatedAt: import("zod").ZodString;
@@ -172,14 +172,14 @@ export declare const portableOccurrenceRecordSchema: import("zod").ZodObject<{
     sequence: import("zod").ZodNumber;
     settledAt: import("zod").ZodOptional<import("zod").ZodString>;
     state: import("zod").ZodEnum<{
-        succeeded: "succeeded";
-        ambiguous: "ambiguous";
-        due: "due";
-        cancelled: "cancelled";
         planned: "planned";
+        due: "due";
         dispatching: "dispatching";
         retry_wait: "retry_wait";
+        ambiguous: "ambiguous";
+        succeeded: "succeeded";
         terminal_failed: "terminal_failed";
+        cancelled: "cancelled";
         skipped_stale: "skipped_stale";
     }>;
     firstAttemptLatenessMs: import("zod").ZodOptional<import("zod").ZodInt>;
@@ -240,8 +240,8 @@ export declare const portableAttemptRecordSchema: import("zod").ZodObject<{
         body: import("zod").ZodOptional<import("zod").ZodObject<{
             contentType: import("zod").ZodString;
             encoding: import("zod").ZodEnum<{
-                utf8: "utf8";
                 base64: "base64";
+                utf8: "utf8";
             }>;
             content: import("zod").ZodString;
             capturedBytes: import("zod").ZodInt;
@@ -276,8 +276,8 @@ export declare const portableAttemptRecordSchema: import("zod").ZodObject<{
     responseStatus: import("zod").ZodOptional<import("zod").ZodNumber>;
     startedAt: import("zod").ZodString;
     state: import("zod").ZodOptional<import("zod").ZodEnum<{
-        succeeded: "succeeded";
         ambiguous: "ambiguous";
+        succeeded: "succeeded";
         retryable_failure: "retryable_failure";
         terminal_failure: "terminal_failure";
     }>>;
@@ -322,9 +322,9 @@ export declare const portableAttemptRecordSchema: import("zod").ZodObject<{
             GET: "GET";
         }>;
         bodyMode: import("zod").ZodEnum<{
+            none: "none";
             envelope: "envelope";
             json: "json";
-            none: "none";
         }>;
         headers: import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
             name: import("zod").ZodString;
@@ -428,8 +428,8 @@ export declare const portableSchedulingRecordSetSchema: import("zod").ZodObject<
             body: import("zod").ZodOptional<import("zod").ZodObject<{
                 contentType: import("zod").ZodString;
                 encoding: import("zod").ZodEnum<{
-                    utf8: "utf8";
                     base64: "base64";
+                    utf8: "utf8";
                 }>;
                 content: import("zod").ZodString;
                 capturedBytes: import("zod").ZodInt;
@@ -464,8 +464,8 @@ export declare const portableSchedulingRecordSetSchema: import("zod").ZodObject<
         responseStatus: import("zod").ZodOptional<import("zod").ZodNumber>;
         startedAt: import("zod").ZodString;
         state: import("zod").ZodOptional<import("zod").ZodEnum<{
-            succeeded: "succeeded";
             ambiguous: "ambiguous";
+            succeeded: "succeeded";
             retryable_failure: "retryable_failure";
             terminal_failure: "terminal_failure";
         }>>;
@@ -510,9 +510,9 @@ export declare const portableSchedulingRecordSetSchema: import("zod").ZodObject<
                 GET: "GET";
             }>;
             bodyMode: import("zod").ZodEnum<{
+                none: "none";
                 envelope: "envelope";
                 json: "json";
-                none: "none";
             }>;
             headers: import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
                 name: import("zod").ZodString;
@@ -565,14 +565,14 @@ export declare const portableSchedulingRecordSetSchema: import("zod").ZodObject<
         sequence: import("zod").ZodNumber;
         settledAt: import("zod").ZodOptional<import("zod").ZodString>;
         state: import("zod").ZodEnum<{
-            succeeded: "succeeded";
-            ambiguous: "ambiguous";
-            due: "due";
-            cancelled: "cancelled";
             planned: "planned";
+            due: "due";
             dispatching: "dispatching";
             retry_wait: "retry_wait";
+            ambiguous: "ambiguous";
+            succeeded: "succeeded";
             terminal_failed: "terminal_failed";
+            cancelled: "cancelled";
             skipped_stale: "skipped_stale";
         }>;
         firstAttemptLatenessMs: import("zod").ZodOptional<import("zod").ZodInt>;
@@ -650,9 +650,9 @@ export declare const portableSchedulingRecordSetSchema: import("zod").ZodObject<
                 GET: "GET";
             }>;
             bodyMode: import("zod").ZodEnum<{
+                none: "none";
                 envelope: "envelope";
                 json: "json";
-                none: "none";
             }>;
             headers: import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
                 name: import("zod").ZodString;
@@ -775,9 +775,9 @@ export declare const portableSchedulingRecordSetSchema: import("zod").ZodObject<
             timeZone: import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<string, string>>;
         }, import("zod/v4/core").$strip>], "kind">;
         status: import("zod").ZodEnum<{
-            paused: "paused";
-            active: "active";
             cancelled: "cancelled";
+            active: "active";
+            paused: "paused";
             completed: "completed";
         }>;
         updatedAt: import("zod").ZodString;