better-supabase 0.5.0 → 0.6.0

package/dist/store-BdH5ruDx.js

@@ -0,0 +1,66 @@
+//#region src/streams/store.ts
+/** A reader that fetches pages and waits for a wake-up or `pollMs` between empty ones. */
+function pollingRead(options) {
+	let next = options.from;
+	let woken = false;
+	let resolveWait;
+	const wake = () => {
+		woken = true;
+		resolveWait?.();
+	};
+	let unsubscribe;
+	const stop = () => {
+		unsubscribe?.();
+		unsubscribe = void 0;
+		options.signal?.removeEventListener("abort", wake);
+	};
+	const wait = () => new Promise((resolve) => {
+		if (woken || options.signal?.aborted) {
+			resolve();
+			return;
+		}
+		const timer = setTimeout(done, options.pollMs);
+		function done() {
+			clearTimeout(timer);
+			resolveWait = void 0;
+			resolve();
+		}
+		resolveWait = done;
+	});
+	return new ReadableStream({
+		start() {
+			options.signal?.addEventListener("abort", wake, { once: true });
+			unsubscribe = options.subscribe?.(wake);
+		},
+		async pull(controller) {
+			for (;;) {
+				if (options.signal?.aborted) {
+					stop();
+					controller.close();
+					return;
+				}
+				woken = false;
+				const page = await options.fetch(next);
+				if (!page.ok) {
+					stop();
+					controller.error(page.error);
+					return;
+				}
+				for (const chunk of page.data.chunks) controller.enqueue(chunk);
+				next = page.data.next;
+				if (page.data.done) {
+					stop();
+					controller.close();
+					return;
+				}
+				if (page.data.chunks.length > 0) return;
+				await wait();
+			}
+		},
+		cancel() {
+			stop();
+		}
+	});
+}
+//#endregion
+export { pollingRead as t };

package/dist/store-CGjgWu5n.d.ts

@@ -0,0 +1,68 @@
+import { t as AsyncResult } from "./result-D7y2fT87.js";
+//#region src/streams/store.d.ts
+/** How a stream is opened. */
+interface StreamOpenOptions {
+  /** The user who may read the stream and cancel it. */
+  readonly owner?: string;
+  readonly tenant?: string;
+  /** What the stream carries, such as `chat` or `workflow`. Defaults to `default`. */
+  readonly kind?: string;
+  /** Seconds the stream lives, or a Postgres interval such as `"2 hours"`. Defaults to one day. */
+  readonly ttl?: number | string;
+}
+interface StreamAppendResult {
+  /** The index the next chunk gets. */
+  readonly next: number;
+  /** Someone asked the writer to stop. */
+  readonly cancelled: boolean;
+}
+interface StreamStatus {
+  /** The number of chunks stored. */
+  readonly next: number;
+  readonly closed: boolean;
+  readonly cancelled: boolean;
+}
+interface StreamReadOptions {
+  /** Ends the stream early. */
+  readonly signal?: AbortSignal;
+}
+interface StreamPurgeOptions {
+  /** How long a closed stream is kept: seconds or an interval. Defaults to one day. */
+  readonly olderThan?: number | string;
+}
+/**
+ * Durable, resumable output: one writer appends ordered text chunks and any
+ * number of readers read from a chunk index, live or after a reconnect.
+ * Chunks keep the index they were appended at, so a reader that counted `n`
+ * chunks resumes with `read(id, n)`.
+ */
+interface StreamStore {
+  readonly apiVersion: 1;
+  readonly name: string;
+  /** Creates the stream; `true` when it was new, `false` when it existed. */
+  open(id: string, options?: StreamOpenOptions): AsyncResult<boolean>;
+  /**
+   * Stores `chunks` at `fromIdx`, `fromIdx + 1`, ... Indexes already stored
+   * are skipped, so a retried batch is harmless. Fails with the hint
+   * `STREAM_NOT_FOUND`, `STREAM_CLOSED` or `STREAM_GAP` (`fromIdx` past the
+   * end).
+   */
+  append(id: string, fromIdx: number, chunks: readonly string[]): AsyncResult<StreamAppendResult>;
+  /**
+   * The chunks from `fromIdx` on, waiting for new ones until the stream is
+   * closed. A stream that doesn't exist (or that the caller can't read) ends
+   * at once. A read error errors the stream with the `DbError`.
+   */
+  read(id: string, fromIdx?: number, options?: StreamReadOptions): ReadableStream<string>;
+  /** The stream's state, or `undefined` when it doesn't exist. */
+  status(id: string): AsyncResult<StreamStatus | undefined>;
+  isCancelled(id: string): AsyncResult<boolean>;
+  /** Marks the stream finished; `false` when it was closed already or doesn't exist. */
+  close(id: string): AsyncResult<boolean>;
+  /** Asks the writer to stop; it learns on its next append. */
+  cancel(id: string): AsyncResult<boolean>;
+  /** Deletes expired streams and closed ones past `olderThan`; resolves with the count. */
+  purge(options?: StreamPurgeOptions): AsyncResult<number>;
+}
+//#endregion
+export { StreamStatus as a, StreamReadOptions as i, StreamOpenOptions as n, StreamStore as o, StreamPurgeOptions as r, StreamAppendResult as t };

package/dist/streams/index.d.ts

@@ -0,0 +1,76 @@
+import { t as AsyncResult, w as ErrorMapper } from "../result-D7y2fT87.js";
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../block-transport-DvaoPuZ9.js";
+import { a as StreamStatus, i as StreamReadOptions, n as StreamOpenOptions, o as StreamStore, r as StreamPurgeOptions, t as StreamAppendResult } from "../store-CGjgWu5n.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/streams/postgres.d.ts
+interface PostgresStreamStoreOptions {
+  /** `sqlTransport(postgres.asService())` for the writer; the owner's transport for reads. */
+  readonly transport: BlockTransport;
+  /** The schema of the `streams` module. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * `realtime` (the default) pings the stream's private topic after each
+   * batch; `poll` skips the ping for apps near the Realtime message quota,
+   * and readers poll instead.
+   */
+  readonly wake?: "realtime" | "poll";
+  /** A Supabase client a reader joins the topic with, to wake up on the ping. */
+  readonly realtime?: Pick<SupabaseClient, "channel" | "removeChannel">;
+  /** `sql.modules.streams.options.topic`. Defaults to `stream`. */
+  readonly topic?: string;
+  /** Milliseconds between reads of an idle stream: 250 by default, 2000 with `realtime`. */
+  readonly pollMs?: number;
+  /** Chunks per read. Defaults to 1000. */
+  readonly batch?: number;
+}
+/** A `StreamStore` on the `streams` SQL module. */
+export declare function postgresStreamStore(options: PostgresStreamStoreOptions): StreamStore;
+//#endregion
+//#region src/streams/tee.d.ts
+interface TeeToStoreOptions extends StreamOpenOptions {
+  /** Milliseconds a chunk may wait before its batch is written. Defaults to 100. */
+  readonly flushMs?: number;
+  /** Bytes that trigger a write before `flushMs`. Defaults to 4096. */
+  readonly flushBytes?: number;
+  /**
+   * Called once when the store reports the stream cancelled. Abort the
+   * generation here, e.g. the `AbortController` passed to `streamText`.
+   */
+  readonly onCancel?: () => void;
+}
+interface TeedStream {
+  /** The source, for the live response. */
+  readonly stream: ReadableStream<string>;
+  /**
+   * Settles once every chunk is stored and the stream is closed, with the
+   * number of chunks. It keeps going after the live client disconnects, so
+   * hand it to `waitUntil` or `after`.
+   */
+  readonly persisted: AsyncResult<number>;
+}
+/**
+ * Copies `source` into `store` under `id` while passing it through. Chunks
+ * are written in batches, each at its own index, so a reader that counted
+ * `n` chunks of the live stream resumes with `read(id, n)`.
+ */
+export declare function teeToStore(store: StreamStore, id: string, source: ReadableStream<string>, options?: TeeToStoreOptions): TeedStream;
+/**
+ * Stores `source` under `id` without a live copy, for a stream the caller
+ * already sends elsewhere (the second branch of its own `tee()`). Settles
+ * like `teeToStore`'s `persisted`.
+ */
+export declare function writeToStore(store: StreamStore, id: string, source: ReadableStream<string>, options?: TeeToStoreOptions): AsyncResult<number>;
+interface ResumeFromStoreOptions {
+  /** The number of chunks the client already has. Defaults to 0. */
+  readonly fromIdx?: number;
+  readonly signal?: AbortSignal;
+}
+/**
+ * The rest of stream `id` from `fromIdx`, or `undefined` when there is
+ * nothing to resume: no such stream, or a closed one the client has read to
+ * the end. A route answers `undefined` with 204.
+ */
+export declare function resumeFromStore(store: StreamStore, id: string, options?: ResumeFromStoreOptions): AsyncResult<ReadableStream<string> | undefined>;
+//#endregion
+export { type BlockTransport, type PostgresStreamStoreOptions, type ResumeFromStoreOptions, type StreamAppendResult, type StreamOpenOptions, type StreamPurgeOptions, type StreamReadOptions, type StreamStatus, type StreamStore, type TeeToStoreOptions, type TeedStream, rpcTransport, sqlTransport };

package/dist/streams/index.js

@@ -0,0 +1,77 @@
+import { n as rpcTransport, r as sqlTransport } from "../block-transport-BLr-ZgLc.js";
+import { D as stringsOf, d as isRecord, i as blockCall, w as seconds, y as recordOf } from "../block-helpers-DWHxHsEQ.js";
+import { n as teeToStore, r as writeToStore, t as resumeFromStore } from "../tee-CoEppCER.js";
+import { t as pollingRead } from "../store-BdH5ruDx.js";
+//#region src/streams/postgres.ts
+function statusOf(value) {
+	if (!isRecord(value)) return void 0;
+	return {
+		next: Number(value["next"] ?? 0),
+		closed: value["closed"] === true,
+		cancelled: value["cancelled"] === true
+	};
+}
+/** A `StreamStore` on the `streams` SQL module. */
+function postgresStreamStore(options) {
+	const call = blockCall(options.transport, options.schema ?? "better_supabase", options.mappers);
+	const wake = (options.wake ?? "realtime") === "realtime";
+	const topic = options.topic ?? "stream";
+	const realtime = wake ? options.realtime : void 0;
+	const pollMs = options.pollMs ?? (realtime ? 2e3 : 250);
+	const batch = options.batch ?? 1e3;
+	const subscribe = realtime ? (id) => (onWake) => {
+		const channel = realtime.channel(`${topic}:${id}`, { config: { private: true } }).on("broadcast", { event: "*" }, onWake).subscribe();
+		return () => {
+			realtime.removeChannel(channel);
+		};
+	} : void 0;
+	const status = (id) => call("stream_status", { stream_id: id }, statusOf);
+	return {
+		apiVersion: 1,
+		name: "postgres",
+		open: (id, open = {}) => call("stream_open", {
+			stream_id: id,
+			owner: open.owner,
+			tenant: open.tenant,
+			kind: open.kind,
+			ttl: open.ttl === void 0 ? void 0 : seconds(open.ttl),
+			wake
+		}, (value) => value === true),
+		append: (id, fromIdx, chunks) => call("stream_append", {
+			stream_id: id,
+			from_idx: fromIdx,
+			chunks: [...chunks]
+		}, (value) => {
+			const row = recordOf(value, "stream_append");
+			return {
+				next: Number(row["next"]),
+				cancelled: row["cancelled"] === true
+			};
+		}),
+		read: (id, fromIdx = 0, read = {}) => pollingRead({
+			from: fromIdx,
+			pollMs,
+			signal: read.signal,
+			...subscribe ? { subscribe: subscribe(id) } : {},
+			fetch: (from) => call("stream_read", {
+				stream_id: id,
+				from_idx: from,
+				max: batch
+			}, (value) => {
+				const row = recordOf(value, "stream_read");
+				return {
+					chunks: stringsOf(row["chunks"]),
+					next: Number(row["next"]),
+					done: row["done"] === true
+				};
+			})
+		}),
+		status,
+		isCancelled: (id) => status(id).map((state) => state?.cancelled === true),
+		close: (id) => call("stream_close", { stream_id: id }, (value) => value === true),
+		cancel: (id) => call("stream_cancel", { stream_id: id }, (value) => value === true),
+		purge: (purge = {}) => call("purge_streams", { older_than: purge.olderThan === void 0 ? void 0 : seconds(purge.olderThan) }, Number)
+	};
+}
+//#endregion
+export { postgresStreamStore, resumeFromStore, rpcTransport, sqlTransport, teeToStore, writeToStore };

package/dist/streams/redis/index.d.ts

@@ -0,0 +1,52 @@
+import { o as StreamStore } from "../../store-CGjgWu5n.js";
+//#region src/streams/redis/redis.d.ts
+/**
+ * The commands the store sends, as node-redis 5 and 6 (`createClient()`)
+ * name them. Any client with these methods works.
+ */
+interface RedisStreamClient {
+  hSetNX(key: string, field: string, value: string): Promise<unknown>;
+  hSet(key: string, field: string, value: string): Promise<unknown>;
+  hGetAll(key: string): Promise<unknown>;
+  rPush(key: string, elements: string[]): Promise<unknown>;
+  lRange(key: string, start: number, stop: number): Promise<unknown>;
+  lLen(key: string): Promise<unknown>;
+  expire(key: string, seconds: number): Promise<unknown>;
+  publish(channel: string, message: string): Promise<unknown>;
+}
+/** A client in subscriber mode, such as `client.duplicate()` after `connect()`. */
+interface RedisStreamSubscriber {
+  subscribe(channel: string, listener: (message: string) => void): Promise<unknown>;
+  unsubscribe(channel: string, listener: (message: string) => void): Promise<unknown>;
+}
+interface RedisStreamSharedOptions {
+  /** Key and channel prefix. Defaults to `bs:stream`. */
+  readonly keyPrefix?: string;
+  /** How long a stream opened without a `ttl` lives. Defaults to `'1 day'`. */
+  readonly ttl?: number | string;
+  /** Milliseconds between reads of an idle stream: 250 by default, 2000 with `subscriber`. */
+  readonly pollMs?: number;
+  /** Chunks per read. Defaults to 1000. */
+  readonly batch?: number;
+}
+type RedisStreamStoreOptions = RedisStreamSharedOptions & ({
+  readonly client: RedisStreamClient;
+  /** Wakes readers on each batch; without it they poll. */
+  readonly subscriber?: RedisStreamSubscriber;
+} | {
+  /**
+   * Connects with `redis` (node-redis, an optional peer) on first use,
+   * with a duplicate connection that wakes readers.
+   */
+  readonly url: string;
+});
+/**
+ * A `StreamStore` on Redis, for apps that keep live output out of Postgres.
+ * Chunks live in a list and the state in a hash, both expiring after the
+ * stream's `ttl`, so `purge` has nothing to do and resolves with 0. Redis
+ * has no row-level security: check that the caller owns the stream before
+ * `read` or `cancel`.
+ */
+export declare function redisStreamStore(options: RedisStreamStoreOptions, load?: () => Promise<unknown>): StreamStore;
+//#endregion
+export type { RedisStreamClient, RedisStreamStoreOptions, RedisStreamSubscriber };

package/dist/streams/redis/index.js

@@ -0,0 +1,185 @@
+import { n as dbError } from "../../errors-B11Duf73.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { d as isRecord } from "../../block-helpers-DWHxHsEQ.js";
+import { t as pollingRead } from "../../store-BdH5ruDx.js";
+//#region src/streams/redis/redis.ts
+const isNodeRedis = (value) => isRecord(value) && typeof value["createClient"] === "function";
+/**
+* Loads `redis` on first use. The specifier is a variable so bundlers leave
+* the optional peer out of apps that pass their own client.
+*/
+async function loadRedis() {
+	const specifier = "redis";
+	try {
+		return await import(specifier);
+	} catch {
+		return;
+	}
+}
+async function connectUrl(url, load) {
+	const module = await load();
+	if (!isNodeRedis(module)) throw new TypeError("redisStreamStore({ url }) needs the redis package: pnpm add redis, or pass a connected client");
+	const client = module.createClient({ url });
+	const subscriber = client.duplicate();
+	await Promise.all([client.connect(), subscriber.connect()]);
+	return {
+		client,
+		subscriber
+	};
+}
+const DAY = 86400;
+const UNITS = {
+	second: 1,
+	minute: 60,
+	hour: 3600,
+	day: DAY
+};
+const INTERVAL = /^(\d+)\s*(second|minute|hour|day)s?$/;
+function ttlSeconds(value) {
+	if (typeof value === "number") return value > 0 ? Math.ceil(value) : void 0;
+	const match = INTERVAL.exec(value.trim());
+	const unit = match?.[2] === void 0 ? void 0 : UNITS[match[2]];
+	return match && unit ? Number(match[1]) * unit : void 0;
+}
+const text = (value) => typeof value === "string" ? value : void 0;
+/**
+* A `StreamStore` on Redis, for apps that keep live output out of Postgres.
+* Chunks live in a list and the state in a hash, both expiring after the
+* stream's `ttl`, so `purge` has nothing to do and resolves with 0. Redis
+* has no row-level security: check that the caller owns the stream before
+* `read` or `cancel`.
+*/
+function redisStreamStore(options, load = loadRedis) {
+	let connected = "client" in options ? Promise.resolve({
+		client: options.client,
+		subscriber: options.subscriber
+	}) : void 0;
+	const connection = () => {
+		if (connected) return connected;
+		if (!("url" in options)) throw new TypeError("redisStreamStore needs a client or a url");
+		const pending = connectUrl(options.url, load);
+		connected = pending;
+		pending.catch(() => {
+			connected = void 0;
+		});
+		return pending;
+	};
+	const redis = async () => (await connection()).client;
+	const prefix = options.keyPrefix ?? "bs:stream";
+	const defaultTtl = ttlSeconds(options.ttl ?? DAY);
+	const wakes = "url" in options || options.subscriber !== void 0;
+	const pollMs = options.pollMs ?? (wakes ? 2e3 : 250);
+	const batch = options.batch ?? 1e3;
+	const meta = (id) => `${prefix}:${id}:meta`;
+	const list = (id) => `${prefix}:${id}:chunks`;
+	const channel = (id) => `${prefix}:${id}`;
+	const state = async (id) => {
+		const value = await (await redis()).hGetAll(meta(id));
+		if (!isRecord(value) || text(value["created"]) === void 0) return void 0;
+		const fields = {};
+		for (const [key, entry] of Object.entries(value)) {
+			const field = text(entry);
+			if (field !== void 0) fields[key] = field;
+		}
+		return fields;
+	};
+	const length = async (id) => Number(await (await redis()).lLen(list(id)));
+	const missing = (id) => dbError("not_found", `stream ${id} does not exist`, { hint: "STREAM_NOT_FOUND" });
+	const attempt = (run) => AsyncResult.from(async () => ok(await run()));
+	const status = (id) => attempt(async () => {
+		const fields = await state(id);
+		if (!fields) return;
+		return {
+			next: await length(id),
+			closed: fields["closed"] !== void 0,
+			cancelled: fields["cancelled"] !== void 0
+		};
+	});
+	const mark = (id, field) => attempt(async () => {
+		const fields = await state(id);
+		if (!fields || fields[field] !== void 0) return false;
+		if (field === "cancelled" && fields["closed"] !== void 0) return false;
+		const client = await redis();
+		await client.hSet(meta(id), field, (/* @__PURE__ */ new Date()).toISOString());
+		await client.publish(channel(id), field === "closed" ? "close" : "cancel");
+		if (field === "cancelled") await client.publish(`${channel(id)}:cancel`, "cancel");
+		return true;
+	});
+	return {
+		apiVersion: 1,
+		name: "redis",
+		open: (id, open = {}) => {
+			const ttl = open.ttl === void 0 ? defaultTtl : ttlSeconds(open.ttl);
+			if (ttl === void 0) return AsyncResult.err(dbError("invalid_input", `ttl must be seconds or "<n> seconds|minutes|hours|days"`));
+			return attempt(async () => {
+				const client = await redis();
+				const created = await client.hSetNX(meta(id), "created", (/* @__PURE__ */ new Date()).toISOString());
+				if (created !== true && Number(created) !== 1) return false;
+				await client.hSet(meta(id), "kind", open.kind ?? "default");
+				if (open.owner !== void 0) await client.hSet(meta(id), "owner", open.owner);
+				if (open.tenant !== void 0) await client.hSet(meta(id), "tenant", open.tenant);
+				await client.hSet(meta(id), "ttl", String(ttl));
+				await client.expire(meta(id), ttl);
+				return true;
+			});
+		},
+		append: (id, fromIdx, chunks) => AsyncResult.from(async () => {
+			const fields = await state(id);
+			if (!fields) return err(missing(id));
+			if (fields["closed"] !== void 0) return err(dbError("raised", `stream ${id} is closed`, { hint: "STREAM_CLOSED" }));
+			const stored = await length(id);
+			if (fromIdx < 0 || fromIdx > stored) return err(dbError("raised", `stream ${id} is at chunk ${String(stored)}, not ${String(fromIdx)}`, { hint: "STREAM_GAP" }));
+			const fresh = chunks.slice(stored - fromIdx);
+			if (fresh.length > 0) {
+				const client = await redis();
+				await client.rPush(list(id), [...fresh]);
+				await client.expire(list(id), Number(fields["ttl"] ?? DAY));
+				await client.publish(channel(id), "append");
+			}
+			return ok({
+				next: Math.max(stored, fromIdx + chunks.length),
+				cancelled: fields["cancelled"] !== void 0
+			});
+		}),
+		read: (id, fromIdx = 0, read = {}) => pollingRead({
+			from: fromIdx,
+			pollMs,
+			signal: read.signal,
+			...wakes ? { subscribe: (wake) => {
+				const listener = () => {
+					wake();
+				};
+				const joined = connection().then(async ({ subscriber }) => {
+					await subscriber?.subscribe(channel(id), listener);
+					return subscriber;
+				});
+				return () => {
+					joined.then((subscriber) => subscriber?.unsubscribe(channel(id), listener)).catch(() => {});
+				};
+			} } : {},
+			fetch: (from) => attempt(async () => {
+				const fields = await state(id);
+				if (!fields) return {
+					chunks: [],
+					next: from,
+					done: true
+				};
+				const value = await (await redis()).lRange(list(id), from, from + batch - 1);
+				const chunks = Array.isArray(value) ? value.map(String) : [];
+				const next = from + chunks.length;
+				return {
+					chunks,
+					next,
+					done: fields["closed"] !== void 0 && next >= await length(id)
+				};
+			})
+		}),
+		status,
+		isCancelled: (id) => status(id).map((value) => value?.cancelled === true),
+		close: (id) => mark(id, "closed"),
+		cancel: (id) => mark(id, "cancelled"),
+		purge: () => AsyncResult.ok(0)
+	};
+}
+//#endregion
+export { redisStreamStore };

package/dist/stripe-BMj5LtsT.js

@@ -0,0 +1,38 @@
+//#region src/blocks/stripe.ts
+const isModule = (value) => typeof value === "object" && value !== null && "default" in value && typeof value.default === "function" && "createFetchHttpClient" in value.default;
+/**
+* Loads `stripe` on first use. The specifier is a variable so bundlers leave
+* the optional peer out of apps that pass their own client; a missing
+* install returns `undefined` and the caller explains how to add it.
+*/
+async function loadStripeModule() {
+	const specifier = "stripe";
+	try {
+		return await import(specifier);
+	} catch {
+		return;
+	}
+}
+/**
+* The client `source` names: itself, or one created with Stripe's fetch HTTP
+* client so it runs on every WinterTC runtime.
+*/
+async function stripeClient(source, load = loadStripeModule) {
+	if (typeof source === "function") return source();
+	if (!("secretKey" in source)) return source;
+	const loaded = await load();
+	if (!isModule(loaded)) throw new TypeError("The billing and usage blocks need the stripe package: pnpm add stripe, or pass a Stripe client as `stripe`");
+	const Stripe = loaded.default;
+	return new Stripe(source.secretKey, {
+		httpClient: Stripe.createFetchHttpClient(),
+		...source.apiVersion === void 0 ? {} : { apiVersion: source.apiVersion }
+	});
+}
+/** Resolves the client once, on first use; a function source runs on every use. */
+function lazyStripe(source) {
+	if (typeof source === "function") return async () => source();
+	let client;
+	return () => client ??= stripeClient(source);
+}
+//#endregion
+export { lazyStripe as t };