kaafil-js 0.4.0 → 0.6.0

package/dist/{vocabulary--cKHiCky.d.cts → vocabulary-RhPJe95T.d.cts}

@@ -10,7 +10,7 @@ interface components {
         };
         AddChecklistItemRequest: {
             /**
-             * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one.
+             * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one. Must match `^[a-z][a-z0-9_]{0,59}$` — snake_case: a leading letter, then lowercase letters, digits and UNDERSCORES only. Hyphens are rejected, which is the usual surprise, since `before-departure` looks lowercase enough.
              * @example pre_departure_docs
              */
             sectionKey: string;
@@ -25,7 +25,7 @@ interface components {
              */
             phase: "PRE_DEPARTURE" | "IN_TRIP" | "POST_TRIP";
             /**
-             * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one.
+             * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one. Must match `^[a-z][a-z0-9_]{0,59}$` — snake_case: a leading letter, then lowercase letters, digits and UNDERSCORES only. Hyphens are rejected, which is the usual surprise, since `before-departure` looks lowercase enough.
              * @example pre_departure_docs
              */
             key?: string;
@@ -324,8 +324,13 @@ interface components {
              * @example 214
              */
             tripsIngested: number;
-            /** @description ACTIVE_MANAGERS UsageRecord total for the current period. Always 0 today — no writer increments this metric yet (`plan.constants.ts#METERED_USAGE_METRICS`). */
+            /** @description ACTIVE_MANAGERS UsageRecord total for the current period — a BILLING METER. Always 0 today: no writer increments this metric yet (`plan.constants.ts#METERED_USAGE_METRICS`). Do NOT render it as a manager count; use `managers`. */
             activeManagers: number;
+            /**
+             * @description How many managers this agency has, counted off the Manager table (soft-deleted rows excluded). This is the headcount a 'Managers' column wants — `activeManagers` above is a meter that nothing writes.
+             * @example 4
+             */
+            managers: number;
             /**
              * @description When `IngestLog` last recorded a row naming this agency, or `null` if never.
              * @example 2026-08-14T09:12:00Z
@@ -1585,7 +1590,7 @@ interface components {
         };
         CreateChecklistTemplateRequest: {
             /**
-             * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one.
+             * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one. Must match `^[a-z][a-z0-9_]{0,59}$` — snake_case: a leading letter, then lowercase letters, digits and UNDERSCORES only. Hyphens are rejected, which is the usual surprise, since `before-departure` looks lowercase enough.
              * @example pre_departure_docs
              */
             key: string;
@@ -1612,7 +1617,7 @@ interface components {
             /** @description The items this template seeds when pulled. Omit for an empty template. */
             items?: {
                 /**
-                 * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one.
+                 * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one. Must match `^[a-z][a-z0-9_]{0,59}$` — snake_case: a leading letter, then lowercase letters, digits and UNDERSCORES only. Hyphens are rejected, which is the usual surprise, since `before-departure` looks lowercase enough.
                  * @example pre_departure_docs
                  */
                 key?: string;
@@ -4847,7 +4852,7 @@ interface components {
             createdAt: string;
             /** @description When this token's row was last changed. */
             updatedAt: string;
-            /** @description The plaintext token. Shown exactly once, on this mint response — Kaafil never returns it again and never logs it. Append it to your own link's URL for the traveller to use as their Bearer credential. */
+            /** @description The plaintext token. Never logged. Append it to your own link's URL for the traveller to use as their Bearer credential. You do not have to store it: `GET /share-tokens/{id}/reveal` returns it again, so a desk can re-send a link instead of regenerating one and breaking the copy a family already has. (Tokens minted before Kaafil stored a recoverable copy answer that route with `token: null`.) */
             token: string;
         };
         NotificationListResponse: {
@@ -5213,7 +5218,7 @@ interface components {
             /** @description The FULL replacement item list for this template, in the order they should sort. */
             items?: {
                 /**
-                 * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one.
+                 * @description A short, lowercase machine key identifying this section or item within the trip's checklist. Stays stable across pushes so later calls can address the same one. Must match `^[a-z][a-z0-9_]{0,59}$` — snake_case: a leading letter, then lowercase letters, digits and UNDERSCORES only. Hyphens are rejected, which is the usual surprise, since `before-departure` looks lowercase enough.
                  * @example pre_departure_docs
                  */
                 key?: string;
@@ -6068,7 +6073,7 @@ interface components {
                  * Format: date-time
                  * @description When your system last changed this record. Kaafil uses it to resolve conflicting writes — last-writer-wins by this timestamp, not by arrival order.
                  */
-                sourceUpdatedAt: string;
+                sourceUpdatedAt?: string;
                 /**
                  * @description This traveller's booking status on this trip.
                  * @enum {string}
@@ -26131,7 +26136,7 @@ interface operations {
                     };
                 };
             };
-            /** @description `VALIDATION_ERROR` — Body/params fail schema validation; `IDEMPOTENCY_KEY_REUSED` — Same Idempotency-Key with a different body (same body replays the stored response); `CAPABILITY_UNAVAILABLE` — Required ingested data absent or capability mode-inapplicable for the trip — capability dark; `READ_ONLY_ROLE` — Write attempted by a COORDINATOR-role manager token — the role is read-only with no exception; `BUSINESS_RULE_VIOLATION` — A domain guard blocked the write; details names the rule; `OUT_OF_TRIP_WINDOW` — A date/time outside the trip's window */
+            /** @description `VALIDATION_ERROR` — Body/params fail schema validation; `IDEMPOTENCY_KEY_REUSED` — Same Idempotency-Key with a different body (same body replays the stored response); `CAPABILITY_UNAVAILABLE` — Required ingested data absent or capability mode-inapplicable for the trip — capability dark; `READ_ONLY_ROLE` — Write attempted by a COORDINATOR-role manager token — the role is read-only with no exception; `BUSINESS_RULE_VIOLATION` — A domain guard blocked the write; details names the rule; `OUT_OF_TRIP_WINDOW` — A date/time outside the trip's window; `STAY_WINDOW_OVERLAP` — Two stay windows of one trip claim the same night (half-open intervals); details names the conflicting window */
             422: {
                 headers: {
                     "X-Request-Id"?: string;
@@ -26141,7 +26146,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorEnvelope"] & {
                         error?: {
                             /** @enum {string} */
-                            code?: "VALIDATION_ERROR" | "IDEMPOTENCY_KEY_REUSED" | "CAPABILITY_UNAVAILABLE" | "READ_ONLY_ROLE" | "BUSINESS_RULE_VIOLATION" | "OUT_OF_TRIP_WINDOW";
+                            code?: "VALIDATION_ERROR" | "IDEMPOTENCY_KEY_REUSED" | "CAPABILITY_UNAVAILABLE" | "READ_ONLY_ROLE" | "BUSINESS_RULE_VIOLATION" | "OUT_OF_TRIP_WINDOW" | "STAY_WINDOW_OVERLAP";
                         };
                     };
                 };
@@ -26736,7 +26741,7 @@ interface operations {
                     };
                 };
             };
-            /** @description `VALIDATION_ERROR` — Body/params fail schema validation; `CAPABILITY_UNAVAILABLE` — Required ingested data absent or capability mode-inapplicable for the trip — capability dark; `READ_ONLY_ROLE` — Write attempted by a COORDINATOR-role manager token — the role is read-only with no exception; `BUSINESS_RULE_VIOLATION` — A domain guard blocked the write; details names the rule */
+            /** @description `VALIDATION_ERROR` — Body/params fail schema validation; `CAPABILITY_UNAVAILABLE` — Required ingested data absent or capability mode-inapplicable for the trip — capability dark; `READ_ONLY_ROLE` — Write attempted by a COORDINATOR-role manager token — the role is read-only with no exception; `BUSINESS_RULE_VIOLATION` — A domain guard blocked the write; details names the rule; `STAY_WINDOW_HAS_ASSIGNMENTS` — Stay-window delete refused: it still holds bed assignments; details carries the occupant and room counts, and ?force=true clears them */
             422: {
                 headers: {
                     "X-Request-Id"?: string;
@@ -26746,7 +26751,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorEnvelope"] & {
                         error?: {
                             /** @enum {string} */
-                            code?: "VALIDATION_ERROR" | "CAPABILITY_UNAVAILABLE" | "READ_ONLY_ROLE" | "BUSINESS_RULE_VIOLATION";
+                            code?: "VALIDATION_ERROR" | "CAPABILITY_UNAVAILABLE" | "READ_ONLY_ROLE" | "BUSINESS_RULE_VIOLATION" | "STAY_WINDOW_HAS_ASSIGNMENTS";
                         };
                     };
                 };
@@ -26896,7 +26901,7 @@ interface operations {
                     };
                 };
             };
-            /** @description `VALIDATION_ERROR` — Body/params fail schema validation; `CAPABILITY_UNAVAILABLE` — Required ingested data absent or capability mode-inapplicable for the trip — capability dark; `READ_ONLY_ROLE` — Write attempted by a COORDINATOR-role manager token — the role is read-only with no exception; `BUSINESS_RULE_VIOLATION` — A domain guard blocked the write; details names the rule; `OUT_OF_TRIP_WINDOW` — A date/time outside the trip's window */
+            /** @description `VALIDATION_ERROR` — Body/params fail schema validation; `CAPABILITY_UNAVAILABLE` — Required ingested data absent or capability mode-inapplicable for the trip — capability dark; `READ_ONLY_ROLE` — Write attempted by a COORDINATOR-role manager token — the role is read-only with no exception; `BUSINESS_RULE_VIOLATION` — A domain guard blocked the write; details names the rule; `OUT_OF_TRIP_WINDOW` — A date/time outside the trip's window; `STAY_WINDOW_OVERLAP` — Two stay windows of one trip claim the same night (half-open intervals); details names the conflicting window */
             422: {
                 headers: {
                     "X-Request-Id"?: string;
@@ -26906,7 +26911,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorEnvelope"] & {
                         error?: {
                             /** @enum {string} */
-                            code?: "VALIDATION_ERROR" | "CAPABILITY_UNAVAILABLE" | "READ_ONLY_ROLE" | "BUSINESS_RULE_VIOLATION" | "OUT_OF_TRIP_WINDOW";
+                            code?: "VALIDATION_ERROR" | "CAPABILITY_UNAVAILABLE" | "READ_ONLY_ROLE" | "BUSINESS_RULE_VIOLATION" | "OUT_OF_TRIP_WINDOW" | "STAY_WINDOW_OVERLAP";
                         };
                     };
                 };
@@ -34237,6 +34242,148 @@ interface operations {
             };
         };
     };
+    deleteFile: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key"?: string;
+                "If-Match": string;
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Withdraw a trip document — removes the stored object, then tombstones the row */
+            204: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuccessEnvelope"] & {
+                        /** @enum {boolean} */
+                        data: false;
+                    };
+                };
+            };
+            /** @description `UNAUTHENTICATED` — Missing/expired credential — the SDK attempts one token refresh first */
+            401: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorEnvelope"] & {
+                        error?: {
+                            /** @enum {string} */
+                            code?: "UNAUTHENTICATED";
+                        };
+                    };
+                };
+            };
+            /** @description `PLAN_FEATURE_DISABLED` — Entitlement flag off for the agency — surface an upgrade prompt */
+            402: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorEnvelope"] & {
+                        error?: {
+                            /** @enum {string} */
+                            code?: "PLAN_FEATURE_DISABLED";
+                        };
+                    };
+                };
+            };
+            /** @description `RESOURCE_NOT_FOUND` — Missing or out-of-scope — the same 404 either way; treat as loss-of-access (purge + surface) */
+            404: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorEnvelope"] & {
+                        error?: {
+                            /** @enum {string} */
+                            code?: "RESOURCE_NOT_FOUND";
+                        };
+                    };
+                };
+            };
+            /** @description `CONFLICT_VERSION` — If-Match/expectedVersion stale; details.currentVersion returned */
+            409: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorEnvelope"] & {
+                        error?: {
+                            /** @enum {string} */
+                            code?: "CONFLICT_VERSION";
+                        };
+                    };
+                };
+            };
+            /** @description `VALIDATION_ERROR` — Body/params fail schema validation; `IDEMPOTENCY_KEY_REUSED` — Same Idempotency-Key with a different body (same body replays the stored response); `CAPABILITY_UNAVAILABLE` — Required ingested data absent or capability mode-inapplicable for the trip — capability dark; `READ_ONLY_ROLE` — Write attempted by a COORDINATOR-role manager token — the role is read-only with no exception; `BUSINESS_RULE_VIOLATION` — A domain guard blocked the write; details names the rule */
+            422: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorEnvelope"] & {
+                        error?: {
+                            /** @enum {string} */
+                            code?: "VALIDATION_ERROR" | "IDEMPOTENCY_KEY_REUSED" | "CAPABILITY_UNAVAILABLE" | "READ_ONLY_ROLE" | "BUSINESS_RULE_VIOLATION";
+                        };
+                    };
+                };
+            };
+            /** @description `RATE_LIMITED` — Per-key/per-token rate limit */
+            429: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    /** @description Seconds until the limiter refills enough to accept another request. Integer, never below 1 on a 429 — `decision()` in `rate-limit.ts` floors it at 1 so `Retry-After: 0` ("retry instantly") never ships on an actual refusal. */
+                    "Retry-After"?: number;
+                    /** @description The ceiling, in requests per window, of the specific limiter tier (IP / API key / share token / bulk-ingest / session-rotation) that refused this request. */
+                    "X-RateLimit-Limit"?: number;
+                    /** @description Requests remaining in the current window for that tier — always 0 on a 429. */
+                    "X-RateLimit-Remaining"?: number;
+                    /** @description Seconds until the window resets — relative, not an absolute epoch, so an offline-first client whose clock is wrong cannot misread it. Same value as `Retry-After` on a 429. */
+                    "X-RateLimit-Reset"?: number;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorEnvelope"] & {
+                        error?: {
+                            /** @enum {string} */
+                            code?: "RATE_LIMITED";
+                        };
+                    };
+                };
+            };
+            /** @description `INTERNAL_ERROR` — Engine fault; safe to retry with backoff (all writes are idempotent); `TENANT_SCOPE_MISSING` — Engine invariant tripped — a query reached the database without tenant scope; always a bug, never client-fixable */
+            500: {
+                headers: {
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorEnvelope"] & {
+                        error?: {
+                            /** @enum {string} */
+                            code?: "INTERNAL_ERROR" | "TENANT_SCOPE_MISSING";
+                        };
+                    };
+                };
+            };
+        };
+    };
     readFileUrl: {
         parameters: {
             query?: never;
@@ -48343,6 +48490,7 @@ declare const OperationId: {
     readonly DeleteBooking: "deleteBooking";
     readonly DeleteChecklistItem: "deleteChecklistItem";
     readonly DeleteChecklistTemplate: "deleteChecklistTemplate";
+    readonly DeleteFile: "deleteFile";
     readonly DeleteForm: "deleteForm";
     readonly DeleteFormField: "deleteFormField";
     readonly DeleteFormSection: "deleteFormSection";
@@ -51467,6 +51615,18 @@ interface ReadFileUrlOptions {
 interface ListFilesOptions extends ListFilesQuery {
     readonly signal?: AbortSignal;
 }
+interface DeleteFileOptions {
+    readonly fileId: string;
+    /**
+     * The `version` from the file as last read. Required, not optional: a
+     * missing `If-Match` and a stale one both answer `409 CONFLICT_VERSION`,
+     * identically confusing either way, so this makes forgetting it impossible
+     * rather than merely discouraged. The SDK builds the header itself.
+     */
+    readonly version: number;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
 interface ReadManagerFileViewOptions {
     readonly fileId: string;
     readonly signal?: AbortSignal;
@@ -51496,6 +51656,29 @@ interface FilesResource {
      * into one manager-doc-viewer-shaped response. See this file's header for
      * why it never refuses on a non-`ready` file the way `url()` does. */
     managerView(options: ReadManagerFileViewOptions): Promise<KaafilResponse<ManagerFileViewResponse>>;
+    /**
+     * `DELETE /api/v1/files/{id}` — withdraw a `trip_document` and DELETE THE
+     * STORED OBJECT. The one call on this resource that destroys bytes.
+     *
+     * `trip_document` ONLY. The other three purposes are evidence owned by a
+     * parent record that decides its own life — a receipt by its expense, an
+     * attachment by its form field, a voucher by its booking (use
+     * `bookings.vouchers.replace`) — so calling this on one is `422
+     * BUSINESS_RULE_VIOLATION`, `details.rule:
+     * "file.deleteRestrictedToTripDocument"`. A `retentionClass` of `financial`
+     * or `consent_evidence` is refused the same way with
+     * `"file.deleteBlockedByRetention"`: those carry an obligation to KEEP.
+     *
+     * Afterwards the id is GONE — `meta()` answers `404`, not the `200`
+     * skeleton a retention-purged file still returns. So unlike a purge, a
+     * withdrawn document cannot be told apart from one that never existed. That
+     * is deliberate; a caller who needs a record of the withdrawal keeps it on
+     * their own side before calling.
+     *
+     * Safe to repeat: a retry after a partial failure finishes the job rather
+     * than erroring.
+     */
+    remove(options: DeleteFileOptions): Promise<KaafilResponse<false>>;
 }
 
 /**
@@ -52108,7 +52291,33 @@ interface ReorderItineraryItemOptions extends ReorderItineraryItemRequest {
     readonly signal?: AbortSignal;
 }
 interface ItineraryItemsResource {
-    /** `POST …/itinerary/items` — appends at the tail of its day. */
+    /**
+     * `POST …/itinerary/items` — APPENDS at the tail of its day.
+     *
+     * This is the one write in the ingest path that is not an upsert, and the
+     * asymmetry is worth stating because everything around it is. `trips.upsert`,
+     * `travellers.pushManifest` and `managers.upsert` are all safe to replay —
+     * push the same payload twice and the second is answered `ignored_stale`.
+     * Call this twice with the same title and you get TWO items on that day.
+     *
+     * ── WHY A RETRY DOES NOT SAVE YOU ──────────────────────────────────────────
+     *
+     * `Idempotency-Key` protects the TRANSPORT: the SDK mints one per call
+     * (`../http/client.ts`'s `execute()`), so a socket that dies after the server
+     * committed cannot create the item twice on the automatic retry.
+     *
+     * It does NOT protect an APPLICATION retry. Re-running your seeding script,
+     * or catching an error and calling `add` again, is a NEW call with a NEW
+     * generated key, and the server appends again. The auto-minting is what makes
+     * this easy to miss — the safety is real and it is guarding a different thing.
+     *
+     * ── WHAT TO DO INSTEAD ─────────────────────────────────────────────────────
+     *
+     * Either pass your own stable `idempotencyKey` derived from the content
+     * (`newIdempotencyKey()` in `../idempotency.ts` explains the shape), or read
+     * the day first with `itinerary.read()` and skip titles already on it. A
+     * seeding script that runs more than once wants the second.
+     */
     add(options: AddItineraryItemOptions): Promise<KaafilResponse<ItineraryItemResponse>>;
     patch(options: PatchItineraryItemOptions): Promise<KaafilResponse<ItineraryItemResponse>>;
     /**
@@ -53453,8 +53662,15 @@ type UpsertTripSegmentInput = Omit<UpsertTripSegment, 'startDate' | 'endDate'> &
     readonly endDate: DateTimeInput;
 };
 type PushManifestTraveller = PushManifestRequest['travellers'][number];
+/**
+ * `sourceUpdatedAt` is OPTIONAL here, unlike every sibling below, because the
+ * wire made it optional for this one entry shape: a desk adding a traveller to
+ * a trip has no "when my system last changed this" instant to send, and the
+ * server stamps the write when it is omitted. A CRM mirroring its own records
+ * still sends its real instant and still wins or loses a race on it.
+ */
 type PushManifestTravellerInput = Omit<PushManifestTraveller, 'sourceUpdatedAt'> & {
-    readonly sourceUpdatedAt: DateTimeInput;
+    readonly sourceUpdatedAt?: DateTimeInput;
 };
 type PushBulkTripsTraveller = NonNullable<PushBulkTripsItem['travellers']>[number];
 type PushBulkTripsTravellerInput = Omit<PushBulkTripsTraveller, 'sourceUpdatedAt'> & {