@relyio/sdk 0.2.1 → 0.4.0

package/dist/{index-B-KiFHbx.d.ts → index-BzOFJJKS.d.ts}

@@ -1,5 +1,6 @@
-import { M as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, G as PathParamsOf, r as ApiResponse, W as Wire, q as RequestConfig, B as BaseContent, c as WhereClause, e as SortOptions, f as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, v as BaseValidationError, u as ValidationViolation, H as components, R as RelyIOConfig } from './index-BsUqCAu8.js';
-import { x as SchemaDefinition, y as SchemaContentTypeNames, a6 as InferContentType, K as SchemaAssetTypeNames, at as InferAssetType, z as SchemaSingletonNames, ac as InferSingleton, J as SchemaSettingsGroupNames, an as InferSettingsGroup, G as SchemaQueryNames, H as SchemaLocaleCodes } from './define-schema-DHvUCKwj.js';
+import { J as MergedRelyIOConfig, A as ApiPath, a as ApiMethod, K as PathParamsOf, t as ApiResponse, W as Wire, s as RequestConfig, B as BaseContent, d as WhereClause, f as SortOptions, g as ContentQueryResult, Q as QueryOptions, C as CreateInput, U as UpdateInput, S as SDKError, x as BaseValidationError, w as ValidationViolation, N as components, O as paths, R as RelyIOConfig } from './index-FDak5ofk.js';
+import { a as SchemaDefinition, b as SchemaContentTypeNames, h as SchemaAssetTypeNames, M as InferAssetType, c as SchemaSingletonNames, t as InferSingleton, g as SchemaSettingsGroupNames, E as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-DzYXk4HL.js';
+import { J as InferContentType } from './define-content-type-CBfnTWSS.js';
 
 /**
  * What a call site supplies beside the route it named.
@@ -38,7 +39,7 @@ declare class HttpClient {
     private baseUrl;
     private defaultHeaders;
     private timeout;
-    private retryConfig;
+    private retryPolicy;
     private debug;
     private logger?;
     private config;
@@ -56,7 +57,16 @@ declare class HttpClient {
         data: unknown;
     } ? Wire<P, M, T>['data'] : never>;
     /**
-     * Make an HTTP request with retry logic
+     * Make an HTTP request, retrying only where a retry is safe.
+     *
+     * The headers are merged **once**, before the first attempt, and every attempt
+     * sends that same object. That is what makes a minted `Idempotency-Key` stable
+     * across the retries of one logical write: the service sees one key and
+     * answers the replay from the original outcome instead of applying it twice.
+     *
+     * The loop always makes one attempt. The incumbent's `while (attempt <
+     * maxAttempts)` made none at `retryAttempts: 0` — a value the config validator
+     * accepts — and then dereferenced an unassigned `lastError`.
      */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
     /**
@@ -99,6 +109,16 @@ declare class HttpClient {
      * Get current base URL
      */
     getBaseUrl(): string;
+    /**
+     * One attempt.
+     *
+     * The caller's `signal` and the timeout both end it, through one controller.
+     * The incumbent handed `fetch` the caller's signal **instead of** its own, so a
+     * request that passed a signal had no timeout at all — and a caller abort then
+     * surfaced as `Request timed out`. `timedOut` is what tells the two apart: a
+     * timeout is a `TimeoutError`, a caller abort is the platform's `AbortError`,
+     * rethrown as it came.
+     */
     private makeRequest;
     /**
      * Filter headers that browsers don't allow to be set manually
@@ -113,7 +133,7 @@ declare class HttpClient {
     private mergeRequestConfig;
     private buildQueryString;
     private headersToObject;
-    private calculateRetryDelay;
+    /** A backoff the caller's abort cuts short; the next attempt then refuses to send. */
     private sleep;
     private log;
 }
@@ -427,13 +447,20 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
  */
 interface RetryableWriteOptions {
     /**
-     * A caller-chosen key that makes a retry of **this** write safe.
+     * A key that makes a retry of **this** write safe.
      *
      * A replay inside the service's window returns the original outcome rather
      * than applying twice. The service derives that response from committed state
      * pinned to the recorded version — it does not store bytes — so a replay after
      * the version has been pruned is refused `RESOURCE_EXPIRED` rather than
      * answered from a stale copy.
+     *
+     * **The SDK mints one when you do not.** It used to be caller-supplied and
+     * nothing else, which meant the default write carried no key while the retry
+     * loop replayed it anyway — the one mechanism that makes a replay safe was
+     * optional on the one path that needed it. Supply your own to make a key
+     * outlive the process: a job that may be restarted wants a key derived from
+     * the work, not one minted per call.
      */
     idempotencyKey?: string;
 }
@@ -2370,11 +2397,166 @@ declare class AdhocQueryClient {
 }
 
 /**
- * Type alias for any schema definition.
- * Uses `any` intentionally to accept schemas with any content types, components, etc.
- * This is necessary for the SDK to be flexible with user-defined schemas.
+ * Content and resource errors.
+ *
+ * `ContentTypeNotFoundError` and `ContentNotFoundError` were deleted at API5.
+ * The mapper reached them by sniffing `CONTENT_TYPE_NOT_FOUND` and
+ * `CONTENT_NOT_FOUND`, neither of which is in the closed vocabulary, so neither
+ * class was reachable. Both cases are `RESOURCE_NOT_FOUND`, whose declared
+ * `details` are `{ kind, id? }` — the same two facts, from the one code a route
+ * can actually declare.
+ */
+declare class ResourceNotFoundError extends SDKError {
+    readonly code = "RESOURCE_NOT_FOUND";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+declare class ResourceConflictError extends SDKError {
+    readonly code = "RESOURCE_CONFLICT";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+declare class ResourceExpiredError extends SDKError {
+    readonly code = "RESOURCE_EXPIRED";
+    readonly retryable = false;
+    constructor(message?: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    getUserMessage(): string;
+}
+/**
+ * "Did the service say this resource does not exist?"
+ *
+ * Reads the **code**, not the status. Four contract codes are 4xx on a read and
+ * only one of them means "not there"; the incumbent checked `statusCode === 404`
+ * on the thrown value, and a second arm duck-typed a plain object for the same
+ * number so a hand-written test double would pass. Both are the branch
+ * `INV-API-CLIENT-IS-DERIVED` forbids where a code exists — and the second one
+ * only existed because the tests faked the boundary (rule 20). They now stub
+ * `fetch`, so the double is gone with the branch.
+ */
+declare function isResourceNotFound(error: unknown): boolean;
+
+/**
+ * `relyio.changes()` — the changes feed as a typed long-poll iterator
+ * (`sdk-surfaces-spec.md` decisions 16–18).
+ *
+ * Long-poll only, on purpose. `GET /v1/changes` is an ordinary cursor-paged
+ * collection the committed document declares, so each poll is one `send` over
+ * the one HTTP client (`INV-SS-ONE-CORE`, `INV-API-CLIENT-IS-DERIVED`). The SSE
+ * branch the route also serves would be a second transport path inside that
+ * client, and `parseResponse` buffers a whole body; it stays for `EventSource`
+ * and curl consumers.
+ */
+
+type PollChanges = paths['/v1/changes']['get'];
+/**
+ * The 200 body the document declares, read from its `application/json` content
+ * **by name**. The route also negotiates `text/event-stream`; naming the JSON
+ * content is what keeps that alternate from changing this type when the
+ * document gains it.
+ */
+type ChangesPageBody = PollChanges['responses'][200]['content']['application/json'];
+/**
+ * One change, as the committed document describes an item of the feed's `data`
+ * (`INV-SS-CHANGE-IS-IDS`: ids, content type, locale, kind and cursor — never a
+ * document).
+ *
+ * Read from the document, never written here: the api's route row names the
+ * `Change` component schema, and a change to it reaches this type when the
+ * document is regenerated. `changes.types.ts` holds it equal to the document's
+ * item, and fails if it is ever `unknown` again.
+ */
+type Change = ChangesPageBody['data'][number];
+/** Why a cursor could no longer be replayed. `unknown` when the message named neither. */
+type ChangesExpiredReason = 'retention' | 'dataset-replaced' | 'unknown';
+/**
+ * `RESOURCE_EXPIRED` from the changes feed: the cursor names a position the
+ * ledger can no longer replay from (`INV-SS-CURSOR-REPLAYS`). The consumer
+ * resyncs from the read path and starts again without a cursor.
+ *
+ * A `ResourceExpiredError`, so code that already catches that still does. The
+ * refusal declares no details, so `reason` is read from the message the api
+ * writes (`apps/services/api/src/changes/changes-request.ts` `refusalOf`).
+ */
+declare class ChangesExpiredError extends ResourceExpiredError {
+    readonly reason: ChangesExpiredReason;
+    /** The base class's signature, so `withContext` can rebuild one. */
+    constructor(message: string, statusCode?: number, cause?: Error, context?: Record<string, unknown>);
+    static of(expired: ResourceExpiredError): ChangesExpiredError;
+}
+interface ChangesOptions {
+    /**
+     * A `page.nextCursor` — or a change's `cursor` — from an earlier poll. Omitted,
+     * the first poll answers the dataset's current position and no changes, at
+     * once, and the feed starts from there.
+     */
+    since?: string;
+    /** Content types to keep. Omitted keeps every type; an empty list is refused (400). */
+    types?: readonly string[];
+    /**
+     * Entry ids to keep. Omitted keeps every entry. The api refuses more than it
+     * allows (100 today) as `REQUEST_INVALID`, thrown from the iterator as an
+     * `InvalidPayloadError` on the first poll; the SDK does not restate the
+     * cap, so it cannot drift from the service's.
+     */
+    ids?: readonly string[];
+    /** Ledger rows one poll scans, 1 to 500; the api defaults to 100. */
+    limit?: number;
+    /**
+     * Ends the iteration. An abort — in flight, between polls, or while waiting
+     * out a `Retry-After` — makes the `for await` **complete**, with no further
+     * request and no `AbortError` thrown into the loop.
+     */
+    signal?: AbortSignal;
+    /**
+     * What to do when the cursor has expired.
+     *
+     * - `'throw'` (default) — the iterator throws {@link ChangesExpiredError}.
+     * - `'resync'` — restart from the dataset's current position and keep going.
+     * - a function — resync, and call it with the error once the new position is
+     *   taken and before any change after it is yielded. This is the observable
+     *   form: whatever the consumer derived from the feed may be stale, so the
+     *   function is where it invalidates everything. The iterator waits for it.
+     */
+    onExpired?: 'throw' | 'resync' | ((expired: ChangesExpiredError) => void | Promise<void>);
+}
+
+/**
+ * Any schema the client can be typed by. `any` is deliberate: the client accepts whatever content
+ * types, components, singletons, queries and settings groups a customer declares.
+ *
+ * This is the constraint `TypedRelyIOClient`'s `TSchema` carries, so `RegisteredSchema` is inferred
+ * against the same one — `createClient` returns `TypedRelyIOClient<RegisteredSchema>`, and a schema
+ * inferred against any wider alias would not be provably inside the client's bound.
  */
 type AnySchemaDefinition = SchemaDefinition<any, any, any, any, any>;
+/**
+ * The seam `relyio generate-types` fills (`INV-SS-TYPES-INFERRED`).
+ *
+ * Empty here on purpose. The generated `schema.ts` augments it —
+ *
+ * ```ts
+ * declare module '@relyio/sdk' {
+ *   interface Register {
+ *     schema: typeof schema
+ *   }
+ * }
+ * ```
+ *
+ * — and from then on `createClient({ apiKey })`, with no generic and no `schema:`, is typed by that
+ * schema. The pattern is TanStack Router's. It is type-level only: nothing at runtime reads it.
+ */
+interface Register {
+}
+/**
+ * The schema the project registered through `Register`, or `undefined` when nothing did — which is
+ * the untyped client, exactly as before the generator ran.
+ */
+type RegisteredSchema = Register extends {
+    schema: infer S extends AnySchemaDefinition;
+} ? S : undefined;
+
 /**
  * Client configuration with optional schema
  */
@@ -2539,6 +2721,32 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * ```
      */
     batch(): BatchBuilder<NonNullable<TSchema>>;
+    /**
+     * Follow the dataset's changes feed: each write this key can see, as ids, in
+     * order, long-polled from `GET /v1/changes`.
+     *
+     * Lazy — nothing is requested until the first `next()`. It runs until
+     * `signal` aborts, which ends the `for await` cleanly rather than throwing.
+     * A change names what changed; refetch it through the ordinary read path
+     * (`INV-SS-CHANGE-IS-IDS`).
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController()
+     * for await (const change of relyio.changes({ since: cursor, types: ['post'], signal: controller.signal })) {
+     *   // { entryId, contentType, locale, kind, cursor }
+     * }
+     * ```
+     *
+     * @example Resync when the cursor has expired
+     * ```typescript
+     * for await (const change of relyio.changes({
+     *   since: cursor,
+     *   onExpired: async () => invalidateEverything(),
+     * })) { … }
+     * ```
+     */
+    changes(options?: ChangesOptions): AsyncIterable<Change>;
     /**
      * Build and execute an ad-hoc query dynamically
      *
@@ -2697,12 +2905,29 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
  * // Content type names autocomplete!
  * const products = await relyio.content('product').fetchAll()
  * ```
- */
+ *
+ * @example After `relyio generate-types` (inferred, `INV-SS-TYPES-INFERRED`)
+ * ```typescript
+ * import { createClient } from '@relyio/sdk'
+ *
+ * // The generated `schema.ts` augments `Register`, so no generic and no `schema:` are needed
+ * const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! })
+ * ```
+ *
+ * The overload without a schema comes first on purpose. Behind the generic one it was never
+ * chosen: with no `schema` to infer from, `TSchema` fell back to its constraint and the call
+ * resolved to `TypedRelyIOClient<AnySchemaDefinition>`. First, it takes every call that passes no
+ * schema, and returns the registered schema's client — or the untyped one when nothing registered.
+ * A `schema:` value fails its `schema?: undefined`, and an explicit generic skips it because it has
+ * no type parameter, so both reach the generic overload unchanged.
+ */
+declare function createClient(config: RelyIOConfig & {
+    schema?: undefined;
+}): TypedRelyIOClient<RegisteredSchema>;
 declare function createClient<TSchema extends AnySchemaDefinition>(config: TypedClientConfig<TSchema>): TypedRelyIOClient<TSchema>;
-declare function createClient(config: RelyIOConfig): TypedRelyIOClient<undefined>;
 /**
  * Helper type to extract schema from client
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { AssetFileBuilder as $, AutocompleteBuilder as A, BatchClient as B, type ClientSchema as C, type BatchOperation as D, type ExtendedQueryResult as E, type BatchOptions as F, type BatchOperationResult as G, HttpClient as H, type BatchSummary as I, type BatchResponse as J, AdhocQueryClient as K, AdhocQueryBuilder as L, type FetchBlock as M, type AggregateBlock as N, type AggregateMetric as O, type SearchBlock as P, type SimilarBlock as Q, type RetryableWriteOptions as R, type SendOptions as S, TypedRelyIOClient as T, type FilterValue as U, type FullTextConfig as V, type AdhocQueryDefinition as W, type AdhocQueryOptions as X, type QueryMetadata as Y, type AdhocQueryResult as Z, AssetClient as _, type TypedClientConfig as a, AssetUploadBuilder as a0, isAssetEntry as a1, type AssetVisibility as a2, type FileStatus as a3, type FileBackend as a4, type AssetFileBlock as a5, type AssetFileExtracted as a6, type AssetUrls as a7, type AssetEntryResponse as a8, type PopulatedAssetReference as a9, type PresignInput as aa, type PresignResult as ab, type ConfirmInput as ac, type ConfirmResult as ad, type ResolveUrlInput as ae, type ResolveUrlResult as af, type CreateAssetOptions as ag, type WaitUntilReadyOptions as ah, type MultipartCreateResult as ai, type MultipartPart as aj, type MultipartTarget as ak, type UploadProgress as al, type FileErrorCode as am, FileUploadError as an, FileValidationError as ao, type FileValidationConstraints as ap, validateFile as aq, type ConditionalWriteOptions as b, createClient as c, ContentClient as d, entityTagOf as e, SingletonClient as f, SettingsClient as g, ContentQueryBuilder as h, ContentByIdBuilder as i, type ChildrenOptions as j, type SingletonFetchOptions as k, type SettingsFetchOptions as l, SearchClient as m, SearchBuilder as n, SimilarBuilder as o, type SearchMode as p, type SearchResultItem as q, type SearchResponse as r, type AutocompleteSuggestion as s, type AutocompleteResponse as t, type SimilarResult as u, type SimilarResponse as v, type SearchFilter as w, type SearchFields as x, BatchBuilder as y, type BatchMethod as z };
+export { type FullTextConfig as $, AutocompleteBuilder as A, type SimilarResult as B, type ClientSchema as C, type SimilarResponse as D, type ExtendedQueryResult as E, type SearchFilter as F, type SearchFields as G, HttpClient as H, BatchClient as I, BatchBuilder as J, type BatchMethod as K, type BatchOperation as L, type BatchOptions as M, type BatchOperationResult as N, type BatchSummary as O, type BatchResponse as P, AdhocQueryClient as Q, type Register as R, type SendOptions as S, TypedRelyIOClient as T, AdhocQueryBuilder as U, type FetchBlock as V, type AggregateBlock as W, type AggregateMetric as X, type SearchBlock as Y, type SimilarBlock as Z, type FilterValue as _, type TypedClientConfig as a, type AdhocQueryDefinition as a0, type AdhocQueryOptions as a1, type QueryMetadata as a2, type AdhocQueryResult as a3, AssetClient as a4, AssetFileBuilder as a5, AssetUploadBuilder as a6, isAssetEntry as a7, type AssetVisibility as a8, type FileStatus as a9, validateFile as aA, type FileBackend as aa, type AssetFileBlock as ab, type AssetFileExtracted as ac, type AssetUrls as ad, type AssetEntryResponse as ae, type PopulatedAssetReference as af, type PresignInput as ag, type PresignResult as ah, type ConfirmInput as ai, type ConfirmResult as aj, type ResolveUrlInput as ak, type ResolveUrlResult as al, type CreateAssetOptions as am, type WaitUntilReadyOptions as an, type MultipartCreateResult as ao, type MultipartPart as ap, type MultipartTarget as aq, type UploadProgress as ar, ResourceNotFoundError as as, ResourceConflictError as at, ResourceExpiredError as au, isResourceNotFound as av, type FileErrorCode as aw, FileUploadError as ax, FileValidationError as ay, type FileValidationConstraints as az, type RegisteredSchema as b, createClient as c, type ConditionalWriteOptions as d, entityTagOf as e, type RetryableWriteOptions as f, ChangesExpiredError as g, type Change as h, type ChangesOptions as i, type ChangesExpiredReason as j, ContentClient as k, SingletonClient as l, SettingsClient as m, ContentQueryBuilder as n, ContentByIdBuilder as o, type ChildrenOptions as p, type SingletonFetchOptions as q, type SettingsFetchOptions as r, SearchClient as s, SearchBuilder as t, SimilarBuilder as u, type SearchMode as v, type SearchResultItem as w, type SearchResponse as x, type AutocompleteSuggestion as y, type AutocompleteResponse as z };