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

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,11 +55,15 @@ 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
@@ -75,9 +82,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,4 +1,4 @@
-export { LeaniError } from "./errors.ts";
+export { LeaniError, TransportError } from "./errors.ts";
 import type { ChangeEnvelope, DurableConsumer, FetchLike, 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";
@@ -203,6 +203,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 +247,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>>;
@@ -296,4 +310,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