@smart-byte/leani-sdk 0.1.0-rc.1 → 0.1.0-rc.3

package/README.md

@@ -29,10 +29,13 @@ const summary = await leani.request<Summary>(
 );
 ```
 
-The client rejects absolute and protocol-relative URLs before attaching a
-bearer token. Prefer the canonical instance-scoped `basePath` from capability
-discovery; short aliases may be absent when several instances share one
-extension.
+The client rejects absolute and protocol-relative URLs, path segments that
+decode to `.` or `..`, backslashes, encoded slashes, backslashes, and percent
+signs, and control characters before attaching a bearer token. Every path
+resolves under the base URL's path, one starting with `/` included, and the SDK
+does not follow redirects. Prefer the canonical instance-scoped `basePath` from
+capability discovery; short aliases may be absent when several instances share
+one extension.
 
 When an alias is absent, pass the discovered canonical path to the typed
 helper instead of giving up its response types:
@@ -52,16 +55,21 @@ Historical subscription orchestration and unified live/history iterators are
 available from `@smart-byte/leani-sdk/backfill`. Required consumers should commit the
 application transaction before acknowledging the Leani-owned durable cursor.
 Destination writes must be idempotent because a crash between those steps can
-replay a change.
+replay a change. Acknowledge a batch's `ackCursor` (or `acknowledgeableCursor`),
+never a change's own cursor; a backfill session's `deliveryBatches()` yields
+every such boundary with its changes, while `events()` yields changes only.
 
 The browser build assumes a same-origin deployment or a reverse proxy that
 adds the application's CORS policy. Leani does not enable cross-origin access
-on its native API by default.
+on its native API by default, and refuses a browser origin that is neither
+loopback nor listed in `api.allowed_origins`. The SDK's mutations without a
+JSON body send `x-leani-request: 1`, which the node requires.
 
 Typed subscriptions accept a configured `processor` instance when a kind is
 ambiguous. `blobs.subscribe()` yields a `{ block, transactions }` payload on
 apply. Check `operation` before reading processor data: a finalized event has
-`{ throughBlock }` instead. Pass an `AbortSignal` to stop an idle stream;
+`{ throughBlock }` instead, or, when `isLiveGapChange()` holds, the
+`{ fromBlock, toBlock }` the live lane skipped. Pass an `AbortSignal` to stop an idle stream;
 leaving the loop cancels its response body.
 
 `queryAndFollow()` returns the first snapshot page and an atomic stream boundary.
@@ -75,9 +83,16 @@ with `boundaryCursor` and `recovery.follow` set to `null`. `queryAndFollow()`
 requires delivery and otherwise returns HTTP 409 `delivery_disabled`.
 
 Both package entry points use `LeaniError` for HTTP failures, including status,
-code, retryability, and request ID. ResetRequiredError is a LeaniError with
+code, retryability, and request ID. A failure below HTTP, such as a refused or
+reset connection or a silent stream, is a retryable `TransportError`, a
+`LeaniError` with status 0. ResetRequiredError is a LeaniError with
 `code: "cursor_expired"`; rebuild application state from a fresh snapshot.
 
 ## License
 
 [MIT](LICENSE).
+
+Development uses the TypeScript 7 native compiler through `@typescript/native`.
+The pinned `typescript` 5.9 package supplies the JavaScript compiler API required
+by `openapi-typescript`; build and typecheck scripts invoke the native compiler
+explicitly so installing both packages cannot change which compiler runs.

package/dist/backfill.d.ts

@@ -1,5 +1,5 @@
-export { LeaniError } from "./errors.ts";
-import type { ChangeEnvelope, DurableConsumer, FetchLike, ProcessorSummary } from "./index.ts";
+export { LeaniError, TransportError } from "./errors.ts";
+import type { ChangeEnvelope, DurableConsumer, FetchLike, ProcessorCoverage, ProcessorSummary } from "./index.ts";
 export type BackfillExecutionMode = "fill_missing" | "recompute";
 export type BackfillState = "waiting_for_consumer" | "queued" | "running" | "backpressured" | "storage_backpressured" | "draining" | "complete_reclaimable" | "completed" | "failed" | "cancelled";
 export interface BackfillRange {
@@ -87,6 +87,16 @@ export type CreateBackfillSubscription = CreateBackfillSubscriptionBase & ({
     fromBlock?: never;
     toBlock?: never;
 });
+/**
+ * The `fill_missing` subscription for the blocks a live gap notice
+ * announces, its `LiveGapChangeData`, or any other range the destination
+ * lacks. Its idempotency key derives from the consumer and the range, so
+ * creating it again, as after the notice is delivered again, returns the
+ * same subscription.
+ */
+export declare function liveGapBackfill(range: BackfillRange, request: Omit<CreateBackfillSubscriptionBase, "mode" | "idempotencyKey"> & {
+    consumer: NonNullable<CreateBackfillSubscriptionBase["consumer"]>;
+}): CreateBackfillSubscription;
 export interface BackfillStreamHello {
     type: "hello";
     apiVersion: "1";
@@ -172,6 +182,9 @@ export interface LiveStreamHello {
     heartbeatIntervalMs: string;
     sessionExpiresAtUnixMs: string;
     leaseTtlMs: string;
+    /** What the processor covers as the session starts: diff it against the
+     * destination to find blocks to request as history. */
+    coverage: ProcessorCoverage;
 }
 export interface LiveStreamBatch<T = unknown> {
     type: "batch";
@@ -203,6 +216,16 @@ export interface DeliverySession<THello, TRecord> extends AsyncIterable<TRecord>
 }
 export interface BackfillDeliverySession<T = unknown> extends DeliverySession<BackfillStreamHello, BackfillStreamRecord<T>> {
     batches(): AsyncIterable<BackfillStreamBatch<T>>;
+    /**
+     * Every acknowledgement boundary with the changes it covers: each batch,
+     * including one without changes, then the completion. Commit `events`,
+     * then acknowledge `ackCursor`.
+     */
+    deliveryBatches(): AsyncIterable<HistoryDeliveryBatch<T>>;
+    /**
+     * The batches' changes, flattened. They carry no acknowledgement
+     * boundary; acknowledge from `deliveryBatches()` or `batches()`.
+     */
     events(): AsyncIterable<ChangeEnvelope<T>>;
 }
 export type LiveDeliverySession<T = unknown> = DeliverySession<LiveStreamHello, LiveStreamRecord<T>>;
@@ -237,6 +260,10 @@ export type UnifiedDeliveryBatch<T = unknown> = {
     completion?: BackfillStreamCompletion;
     record: BackfillStreamBatch<T> | BackfillStreamCompletion;
 };
+/** One history lane's batch, as `BackfillDeliverySession.deliveryBatches()` yields it. */
+export type HistoryDeliveryBatch<T = unknown> = Extract<UnifiedDeliveryBatch<T>, {
+    laneKind: "history";
+}>;
 export interface MultiLaneDelivery<T = unknown> {
     batches(): AsyncIterable<UnifiedDeliveryBatch<T>>;
     liveBatches(): AsyncIterable<UnifiedDeliveryBatch<T>>;
@@ -271,8 +298,18 @@ export interface BackfillSubscriptionClient {
     cancel(subscription: string, options?: {
         signal?: AbortSignal;
     }): Promise<BackfillStatus>;
+    /** Re-queue a failed subscription to resume from its committed progress. */
+    retry(subscription: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<BackfillStatus>;
+    /**
+     * Delete a terminal subscription. A failed or cancelled one is refused
+     * while its required consumer has unacknowledged records, unless
+     * `discardUnacknowledged` is set.
+     */
     delete(subscription: string, options?: {
         signal?: AbortSignal;
+        discardUnacknowledged?: boolean;
     }): Promise<HistoricalWorkDeletion>;
     changes<T = unknown>(subscription: string, consumer: string, options?: {
         credential?: string;
@@ -296,4 +333,3 @@ export interface BackfillSubscriptionClient {
 }
 export declare function createBackfillSubscriptionClient(options: BackfillSubscriptionClientOptions): BackfillSubscriptionClient;
 export declare function parseNdjson(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<unknown>;
-//# sourceMappingURL=backfill.d.ts.map