@abloatai/ablo 0.26.0 → 0.28.0

package/dist/environment.js

@@ -1,16 +1,37 @@
 import { z } from 'zod';
+/**
+ * The two environments an Ablo project runs in: `production` for live data and
+ * `sandbox` for isolated test data. Every credential and every stored row
+ * belongs to exactly one of them.
+ */
 export const ENVIRONMENTS = ['production', 'sandbox'];
+/** A Zod schema that validates a value as one of the {@link ENVIRONMENTS}. */
 export const environmentSchema = z.enum(ENVIRONMENTS);
+/**
+ * Coerces an untrusted value into a valid {@link Environment}, returning
+ * `fallback` (which defaults to `'production'`) when the value is not a
+ * recognized environment. Use it when reading an environment from configuration
+ * or off the wire.
+ */
 export function normalizeEnvironment(value, fallback = 'production') {
     const parsed = environmentSchema.safeParse(value);
     return parsed.success ? parsed.data : fallback;
 }
+/**
+ * Maps an API-key prefix spelling to its {@link Environment}: a `'test'` key
+ * operates on the sandbox, and anything else on production.
+ */
 export function environmentFromKeyPrefix(value) {
     return value === 'test' ? 'sandbox' : 'production';
 }
+/**
+ * Maps an {@link Environment} to the spelling used in an API-key prefix: the
+ * sandbox is `'test'` and production is `'live'`.
+ */
 export function environmentToKeyPrefix(value) {
     return value === 'sandbox' ? 'test' : 'live';
 }
+/** Returns true when the given environment is the sandbox. */
 export function isSandboxEnvironment(value) {
     return value === 'sandbox';
 }

package/dist/errorCodes.d.ts

@@ -1,74 +1,76 @@
 /**
- * The canonical Ablo error-code registry — the **`code` tier** of the
- * Stripe-style two-tier error model.
+ * The registry of every stable error code Ablo can produce. Error handling has
+ * two levels, and this file defines the finer one.
  *
- * ### The two tiers (mirrors Stripe)
+ *   - The `type` is the coarse category, and each one corresponds to an
+ *     {@link AbloError} subclass such as `AbloPermissionError` or
+ *     `AbloValidationError`. Catching by `instanceof` is equivalent to switching
+ *     on `error.type`.
+ *   - The `code` is the fine-grained, machine-readable identifier defined here,
+ *     written in `snake_case` (for example `entity_claimed` or `queue_too_deep`).
+ *     This is what you switch on to handle a specific situation, and what the
+ *     documentation link for an error is built from.
  *
- *   - **`type`** — coarse category, 1:1 with an {@link AbloError} subclass
- *     (`AbloPermissionError`, `AbloValidationError`, …). "Catch by
- *     `instanceof`" ≡ "switch on `e.type`". This tier lives in `errors.ts`.
- *   - **`code`** — the fine-grained, machine-readable identifier in this
- *     file. `snake_case`, ordered noun→state (`entity_claimed`) or
- *     condition→constraint (`queue_too_deep`). This is what callers
- *     `switch` on for specific handling, and what `doc_url` is derived from.
+ * The client, the server, and the tool-calling boundary all speak this same
+ * vocabulary, which makes the registry part of the API contract. Two things
+ * follow from that:
  *
- * Because sync-engine ↔ sync-server ↔ MCP all speak this code vocabulary,
- * the registry **is** the wire contract. Two consequences:
- *
- *   1. `ErrorCode` is a *closed* union (plus the `policy:${string}`
- *      dynamic family). Producing an unregistered code is a compile error
- *      — that's the whole point. {@link AbloError}'s constructor param is
- *      narrowed to `ErrorCode`; only the wire-parse boundary
- *      (`translateHttpError`, frame deserialization) casts an incoming
- *      string to `ErrorCode`, so an *older* SDK still tolerates a *newer*
- *      server's code (forward compat) while internal producers stay checked.
- *   2. The `surface: 'wire'` subset is what an HTTP/MCP boundary maps from
- *      and what the public error docs are generated from. `surface:
- *      'client'` codes are local SDK invariants (you forgot to open the DB,
- *      a model isn't registered) — never sent over the network, so they
- *      carry no `httpStatus`, exactly as Stripe omits client-side
- *      programmer errors from its published code list.
+ *   1. {@link ErrorCode} is a closed set — plus the dynamic `policy:${string}`
+ *      family — so producing a code that is not registered here is a
+ *      compile-time error. The {@link AbloError} constructor accepts only a
+ *      registered code. The one place an arbitrary string is accepted as a code
+ *      is where an incoming response is parsed, which lets an older client
+ *      tolerate a code from a newer server it does not yet recognize.
+ *   2. The codes marked `surface: 'wire'` are the ones that cross the network
+ *      and are mapped at the HTTP and tool-calling boundaries; the public error
+ *      documentation is generated from them. Codes marked `surface: 'client'`
+ *      describe local mistakes — accessing the database before opening it, or
+ *      writing to a model that was never registered — and are never sent over
+ *      the network, so they carry no HTTP status.
  */
 import { z } from 'zod';
 /**
- * Version of the error contract — the envelope shape + the set of codes and
- * their semantics. Date-based, like Stripe's API versions. Bump it (and only
- * it) when the contract changes in a way consumers can observe: a new/removed
- * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
- * and on the `Ablo-Version` response header so a consumer can detect drift.
+ * The version of the error contract: the envelope shape together with the set of
+ * codes and their meanings. It is date-based, and changes only when the contract
+ * changes in a way a consumer can observe — a code added or removed, an HTTP
+ * status changed, or an envelope field changed. It is emitted in the generated
+ * error documentation and returned on the `Ablo-Version` response header, so a
+ * consumer can detect when its expected contract has drifted from the server's.
  */
 export declare const ERROR_CONTRACT_VERSION = "2026-07-03";
-/** Coarse grouping for metrics dashboards and docs sectioning. */
+/** A coarse grouping of error codes, used to organize metrics and documentation. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /**
- * The closed taxonomy of *how a failure recovers* — one rung above the raw
- * `code`. Where `code` says **what** went wrong, `RecoveryClass` says **what
- * the client should do about it**, which is exactly the discriminant the sync
- * FSM and the network probe need. It collapses what used to be three scattered
- * booleans (`retryable`, `authBlocked`, `sessionValid`) into one exhaustive,
- * Zod-validated enum so the connection layer branches on a single value with
- * compile-time completeness instead of ad-hoc `if (!isRetryableCode(...))`
- * chains.
+ * A closed classification of how a failure can be recovered from — a level above
+ * the raw {@link ErrorCode}. Where a code says what went wrong, a recovery class
+ * says what a client should do about it, which is exactly the distinction the
+ * connection layer needs to decide between retrying, re-minting a credential, and
+ * signing the user out. Every code maps to one of these, and the set is
+ * validated at runtime.
  *
- *   - `access_credential_expiry` — the Stripe-style ephemeral key (`ek_`/`rk_`)
- *     the sync-engine presents as its Bearer has expired. The long-lived login
- *     is fine; the remedy is to silently RE-MINT a fresh key from the session
- *     and retry the same request. This MUST NOT sign the user out (the whole
- *     point of the wake-from-sleep fix: a 15-min `ek_` dying after a laptop nap
- *     is routine, not a logout).
- *   - `session_expiry` — the LONG-LIVED login itself is gone. Terminal:
+ *   - `access_credential_expiry` — the short-lived access credential the client
+ *     presents (its ephemeral `ek_` or `rk_` key) has expired, while the
+ *     underlying login is still valid. The remedy is to mint a fresh key from the
+ *     session and retry the same request. This does not sign the user out; a
+ *     short-lived key expiring — for example after a laptop resumes from sleep —
+ *     is routine.
+ *   - `session_expiry` — the long-lived login itself is gone. This is terminal:
  *     sign out and route to re-authentication.
- *   - `auth_blocked` — reachable, but the credential TYPE/config was rejected
- *     (wrong key kind, untrusted issuer, no org). Re-auth re-mints the same
- *     rejected credential and loops, so STOP — don't reconnect, don't sign out.
- *   - `permission` — a 403 authorization denial (scope/role/membership).
- *   - `transient` — retry the same request unchanged (5xx, lease contention…).
- *   - `none` — not a recoverable-auth condition (validation, not-found, local
- *     invariants, and any forward-compat code an older SDK doesn't know).
+ *   - `auth_blocked` — the server was reachable but rejected the kind or
+ *     configuration of the credential (wrong key type, untrusted issuer, no
+ *     organization). Re-authenticating would present the same rejected credential
+ *     and loop, so the client should stop rather than reconnect or sign out.
+ *   - `permission` — an authorization denial (403) based on scope, role, or
+ *     membership.
+ *   - `transient` — a temporary failure, such as a server error or lease
+ *     contention, that may succeed if the same request is retried unchanged.
+ *   - `none` — not a recoverable authentication condition: validation errors,
+ *     not-found, local invariants, and any code an older client does not
+ *     recognize.
  */
 export declare const RECOVERY_CLASSES: readonly ["access_credential_expiry", "session_expiry", "auth_blocked", "permission", "transient", "none"];
-/** Zod enum derived from {@link RECOVERY_CLASSES} — the runtime-validatable
- *  form of the recovery taxonomy. */
+/** A Zod enum over {@link RECOVERY_CLASSES}, for validating a recovery class at
+ *  runtime. */
 export declare const recoveryClassSchema: z.ZodEnum<{
     permission: "permission";
     access_credential_expiry: "access_credential_expiry";
@@ -77,36 +79,40 @@ export declare const recoveryClassSchema: z.ZodEnum<{
     transient: "transient";
     none: "none";
 }>;
-/** How a failure recovers. See {@link RECOVERY_CLASSES}. */
+/** The recovery classification of a failure. See {@link RECOVERY_CLASSES}. */
 export type RecoveryClass = z.infer<typeof recoveryClassSchema>;
-/** One registry entry. `httpStatus` is present only for `surface: 'wire'`
- *  codes — status is a property of the wire boundary, never of a
- *  purely-local client invariant. */
+/** One entry in the registry: everything known about a single error code.
+ *  `httpStatus` is present only for codes that cross the network, since an HTTP
+ *  status is a property of the wire boundary rather than of a purely local
+ *  error. */
 export interface ErrorCodeSpec {
     readonly category: ErrorCategory;
-    /** `'wire'` = crosses the network and is part of the API/MCP contract;
-     *  `'client'` = local SDK invariant, never serialized. */
+    /** `'wire'` for a code that crosses the network and is part of the API
+     *  contract; `'client'` for a local error that is never serialized. */
     readonly surface: 'wire' | 'client';
     /** Canonical HTTP status for the wire boundary. Omitted for client codes. */
     readonly httpStatus?: number;
-    /** Whether the same request can succeed on a later retry without the
-     *  caller changing anything. `false` for permission / validation /
-     *  not-found; `true` for transient transport / lease contention. */
+    /** Whether the same request can succeed on a later retry without the caller
+     *  changing anything. `false` for permission, validation, and not-found;
+     *  `true` for transient transport failures and lease contention. */
     readonly retryable: boolean;
-    /** One-line human description — the source text for the `doc_url` page. */
+    /** A one-line, human-readable description of the error — also the source text
+     *  for its documentation page. */
     readonly message: string;
     /**
-     * Explicit recovery class. Set ONLY where it diverges from what `category` /
-     * `httpStatus` / `retryable` already imply — i.e. the handful of auth codes
-     * whose remedy (`session_expiry` vs `access_credential_expiry`) the bare
-     * status can't distinguish. Everything else is derived by
-     * {@link classifyRecovery}, so adding a normal code needs no `recovery`.
+     * An explicit {@link RecoveryClass}, set only where it differs from what the
+     * category, HTTP status, and `retryable` flag already imply — mainly the few
+     * authentication codes whose remedy the status alone cannot reveal, such as
+     * telling a session expiry apart from an access-credential expiry. For every
+     * other code the recovery class is derived by {@link classifyRecovery}, so
+     * this field can be left unset.
      */
     readonly recovery?: RecoveryClass;
 }
 /**
- * The closed set of stable error codes. Add a code here BEFORE throwing it
- * — the narrowed {@link AbloError} constructor param enforces this.
+ * The complete set of stable error codes, keyed by code. A code must be added
+ * here before it can be thrown, since the {@link AbloError} constructor accepts
+ * only codes from this set.
  */
 export declare const ERROR_CODES: {
     readonly apikey_invalid: ErrorCodeSpec;
@@ -317,6 +323,7 @@ export declare const ERROR_CODES: {
     readonly protocol_version_unsupported: ErrorCodeSpec;
     readonly database_unreachable: ErrorCodeSpec;
     readonly database_not_replication_ready: ErrorCodeSpec;
+    readonly replication_publication_drift: ErrorCodeSpec;
     readonly query_unknown_relation: ErrorCodeSpec;
     readonly query_relation_target_unknown: ErrorCodeSpec;
     readonly query_invalid_identifier: ErrorCodeSpec;
@@ -349,41 +356,42 @@ export declare const ERROR_CODES: {
     readonly incompatible_change: ErrorCodeSpec;
 };
 /**
- * The closed set of registered codes, plus the `policy:${reason}` dynamic
- * family (conflict-policy rejections name their reason inline, the same way
- * Stripe carries a `decline_code` sub-detail). The constructor of
- * {@link AbloError} narrows its `code` option to this type, so a typo or an
- * unregistered code is a compile error. The wire-parse boundary casts
- * incoming strings to this type to preserve forward compatibility.
+ * The type of a valid error code: any key registered in {@link ERROR_CODES},
+ * plus the dynamic `policy:${reason}` family, where a conflict-policy rejection
+ * names its reason inline. The {@link AbloError} constructor accepts only this
+ * type, so a typo or an unregistered code is a compile-time error. Only the
+ * boundary that parses an incoming response casts an arbitrary string to this
+ * type, which preserves forward compatibility with a newer server.
  */
 export type ErrorCode = keyof typeof ERROR_CODES | `policy:${string}`;
-/** The subset of codes that cross the network — the actual API/MCP wire
- *  contract. HTTP/MCP boundaries map from this set; docs are generated
- *  from it. */
+/** The subset of {@link ErrorCode} values that cross the network — the codes
+ *  that make up the API contract, from which the HTTP and tool-calling
+ *  boundaries map and the public documentation is generated. */
 export type WireErrorCode = {
     [K in keyof typeof ERROR_CODES]: (typeof ERROR_CODES)[K]['surface'] extends 'wire' ? K : never;
 }[keyof typeof ERROR_CODES];
-/** Look up an error code's spec. Returns `undefined` for the dynamic
- *  `policy:*` family and for any forward-compat code an older SDK doesn't
- *  yet know. */
+/** Looks up the {@link ErrorCodeSpec} for a code. Returns `undefined` for the
+ *  dynamic `policy:*` family and for any newer code this client does not yet
+ *  recognize. */
 export declare function errorCodeSpec(code: string): ErrorCodeSpec | undefined;
-/** Whether a code's spec marks it retryable. Unknown / dynamic codes
- *  default to non-retryable (safe default — don't auto-retry the unknown). */
+/** Reports whether a code is marked retryable. Unknown and dynamic codes
+ *  default to non-retryable, so an unrecognized failure is never retried
+ *  automatically. */
 export declare function isRetryableCode(code: string): boolean;
 /**
- * Classify a `code` into its {@link RecoveryClass} — the single discriminant
- * the connection FSM and the network probe branch on.
+ * Classifies a code into its {@link RecoveryClass} — the single value the
+ * connection layer and the network probe branch on to decide how to recover.
  *
- * The registry stays the source of truth: an explicit `spec.recovery` wins
- * (set only on the few auth codes whose remedy the status can't reveal), and
- * everything else is DERIVED from the spec so the registry stays terse:
- *   - retryable                → `transient`
- *   - 403                      → `permission`
- *   - residual `auth`-category → `auth_blocked` (the 401 credential-type codes)
- *   - otherwise / unknown      → `none`
+ * The registry is the source of truth. An explicit `recovery` on the code's spec
+ * wins; it is set only on the few authentication codes whose remedy the HTTP
+ * status cannot reveal. Every other code is derived from its spec:
+ *   - retryable                 → `transient`
+ *   - HTTP 403                  → `permission`
+ *   - remaining `auth` category → `auth_blocked` (the credential-type 401s)
+ *   - anything else, or unknown → `none`
  *
- * Unknown / dynamic `policy:*` / forward-compat codes (`spec === undefined`)
- * default to `none`, mirroring {@link isRetryableCode}'s safe default — never
- * silently treat an unrecognised code as a credential expiry or a logout.
+ * An unknown code, a dynamic `policy:*` code, or a code this client predates
+ * (no spec) defaults to `none`, the same safe default as {@link isRetryableCode}:
+ * an unrecognized code is never treated as a credential expiry or a sign-out.
  */
 export declare function classifyRecovery(code: string): RecoveryClass;