@s2-dev/streamstore 0.15.12 → 0.16.0

package/examples/append.ts

@@ -0,0 +1,84 @@
+import { AppendRecord, S2 } from "../src";
+
+const s2 = new S2({
+	accessToken: process.env.S2_ACCESS_TOKEN!,
+});
+
+const basins = await s2.basins.list();
+if (!basins.basins[0]) {
+	throw new Error("No basin found");
+}
+const basin = s2.basin(basins.basins[0].name);
+const streams = await basin.streams.list();
+if (streams.streams[0]) {
+	const stream = basin.stream(streams.streams[0].name);
+	// Create an append session
+	const session = await stream.appendSession();
+
+	// Create a batcher with options
+	const batcher = session.makeBatcher({
+		lingerDuration: 20, // 20ms
+		maxBatchSize: 10,
+	});
+
+	// Submit individual records to the batcher
+	// These will be batched and sent automatically
+	// Now returns promises that resolve when acks are received
+	const promise1 = batcher.submit(AppendRecord.make("record 1"));
+	const promise2 = batcher.submit(AppendRecord.make("record 2"));
+	const promise3 = batcher.submit([
+		AppendRecord.make("record 3"),
+		AppendRecord.make("record 4"),
+	]);
+
+	// You can also submit directly to the session (bypasses batching)
+	const urgentPromise = session.submit(AppendRecord.make("urgent record"));
+
+	// The batcher will continue batching
+	const promise4 = batcher.submit(AppendRecord.make("record 5"));
+
+	// Wait for all acks to come back
+	const allAcks = await Promise.all([
+		promise1,
+		promise2,
+		promise3,
+		urgentPromise,
+		promise4,
+	]);
+	console.log("All records acknowledged:", allAcks);
+
+	// Flush and close the batcher
+	batcher.flush();
+	await batcher.close();
+
+	// Close the session (waits for all appends to complete)
+	await session.close();
+
+	// You can also use the acks stream to track acknowledgements
+	const session2 = await stream.appendSession();
+	const acks = session2.acks();
+
+	// Read acks in parallel with submitting
+	(async () => {
+		for await (const ack of acks) {
+			console.log("Received ack:", ack);
+		}
+	})();
+
+	const ack = await session2.submit([{ body: "test" }]);
+	console.log("Single record ack:", ack);
+
+	await session2.close();
+
+	// Example: Error handling with promises
+	const session3 = await stream.appendSession();
+	try {
+		const errorPromise = session3.submit([{ body: "will fail" }]);
+		// If there's an error (e.g., network issue, validation error),
+		// the promise will reject
+		await errorPromise;
+	} catch (error) {
+		console.error("Append failed:", error);
+	}
+	await session3.close();
+}

package/examples/kitchen-sink.ts

@@ -0,0 +1,73 @@
+import { AppendRecord, S2 } from "../src";
+
+const s2 = new S2({
+	accessToken: process.env.S2_ACCESS_TOKEN!,
+});
+
+const basins = await s2.basins.list();
+console.log(
+	"basins",
+	basins.basins.map((basin) => basin.name),
+);
+if (!basins.basins[0]) {
+	throw new Error("No basin found");
+}
+const basin = s2.basin(basins.basins[0].name);
+const streams = await basin.streams.list();
+const streamResults = await Promise.all(
+	streams.streams.map((stream) =>
+		basin.streams.getConfig({ stream: stream.name }),
+	),
+);
+console.log("streams", streamResults);
+
+if (streams.streams[0]) {
+	console.log("reading stream", streams.streams[0].name);
+	const stream = basin.stream(streams.streams[0].name);
+	const stringRead = await stream.read({
+		count: 5,
+		seq_num: 0,
+	});
+	console.log(
+		"read",
+		stringRead.records?.[0]?.body,
+		stringRead.records?.[0]?.headers,
+	);
+	const bytesRead = await stream.read({ as: "bytes", count: 5, seq_num: 0 });
+	console.log(
+		"read bytes",
+		bytesRead.records?.[0]?.body,
+		bytesRead.records?.[0]?.headers,
+	);
+
+	const append = await stream.append([
+		AppendRecord.make("Hello, world!", {
+			foo: "bar",
+		}),
+		AppendRecord.make(new Uint8Array([1, 2, 3]), {
+			foo: "bar",
+		}),
+		AppendRecord.make(new Uint8Array([1, 2, 3]), [
+			[new TextEncoder().encode("foo"), new TextEncoder().encode("bar")],
+			[new TextEncoder().encode("baz"), "bak"],
+			["qux", new TextEncoder().encode("quux")],
+		]),
+		AppendRecord.fence("my-fence"),
+		AppendRecord.trim(0),
+		AppendRecord.command("foo"),
+		// still can just make by hand:
+		{
+			body: "hello, world!",
+			headers: [["foo", "bar"]],
+			timestamp: new Date().getTime(),
+		},
+	]);
+	console.log("append", append);
+	const readSession = await stream.readSession({
+		clamp: true,
+		tail_offset: 10,
+	});
+	for await (const record of readSession) {
+		console.log("record", record);
+	}
+}

package/examples/read.ts

@@ -0,0 +1,30 @@
+import { S2 } from "../src";
+
+const s2 = new S2({
+	accessToken: process.env.S2_ACCESS_TOKEN!,
+});
+
+const basins = await s2.basins.list();
+if (!basins.basins[0]) {
+	throw new Error("No basin found");
+}
+const basin = s2.basin(basins.basins[0].name);
+const streams = await basin.streams.list();
+if (streams.streams[0]) {
+	const stream = basin.stream(streams.streams[0].name);
+	console.log(
+		`reading s2://${basins.basins[0].name}/${streams.streams[0].name}`,
+	);
+
+	const readSession = await stream.readSession({
+		tail_offset: 5,
+		wait: 10, // wait up to 10 seconds for new records
+		as: "bytes",
+	});
+
+	for await (const record of readSession) {
+		console.log(`[seq ${record.seq_num}] ${record.body}`);
+		console.log("new tail", readSession.streamPosition?.seq_num);
+	}
+	console.log("Done reading");
+}

package/openapi-ts.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "@hey-api/openapi-ts";
+
+export default defineConfig({
+  input:
+    "https://raw.githubusercontent.com/s2-streamstore/s2-protos/refs/heads/main/s2/v1/openapi.json", // sign up at app.heyapi.dev
+  output: "src/generated",
+});

package/package.json

@@ -1,147 +1,39 @@
 {
   "name": "@s2-dev/streamstore",
-  "version": "0.15.12",
-  "author": "Speakeasy",
+  "version": "0.16.0",
   "type": "module",
-  "bin": {
-    "mcp": "bin/mcp-server.js"
-  },
-  "tshy": {
-    "sourceDialects": [
-      "@s2-dev/streamstore/source"
-    ],
-    "exports": {
-      ".": "./src/index.ts",
-      "./package.json": "./package.json",
-      "./types": "./src/types/index.ts",
-      "./models/errors": "./src/models/errors/index.ts",
-      "./models/components": "./src/models/components/index.ts",
-      "./models/operations": "./src/models/operations/index.ts",
-      "./*.js": "./src/*.ts",
-      "./*": "./src/*.ts"
-    }
-  },
-  "sideEffects": false,
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/s2-streamstore/s2-sdk-typescript.git"
-  },
   "scripts": {
-    "lint": "eslint --cache --max-warnings=0 src",
-    "build:mcp": "bun src/mcp-server/build.mts",
-    "build": "npm run build:mcp && tshy",
-    "prepublishOnly": "npm run build"
-  },
-  "peerDependencies": {
-    "@modelcontextprotocol/sdk": ">=1.5.0 <1.10.0"
-  },
-  "peerDependenciesMeta": {
-    "@modelcontextprotocol/sdk": {
-      "optional": true
+    "build": "tsc --project tsconfig.build.json",
+    "test": "vitest --run",
+    "check": "biome check && tsc --noEmit",
+    "check:write": "biome check --write",
+    "format": "biome format --write",
+    "gen:openapi": "openapi-ts",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "bun run build && changeset publish --access public"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     }
   },
   "devDependencies": {
-    "@eslint/js": "^9.19.0",
-    "@modelcontextprotocol/sdk": ">=1.5.0 <1.10.0",
-    "@stricli/core": "^1.1.1",
-    "@types/express": "^4.17.21",
-    "@types/node": "^22.13.1",
-    "@types/uuid": "^9.0.8",
-    "bun": "1.2.17",
-    "bun-types": "1.2.17",
-    "eslint": "^9.19.0",
-    "express": "^4.21.2",
-    "globals": "^15.14.0",
-    "tshy": "^2.0.0",
-    "typescript": "~5.8.3",
-    "typescript-eslint": "^8.26.0"
-  },
-  "dependencies": {
-    "jsonpath-rfc9535": "1.1.0",
-    "uuid": "^9.0.1",
-    "zod": "^3.20.0"
+    "@biomejs/biome": "2.2.5",
+    "@changesets/cli": "^2.29.7",
+    "@hey-api/openapi-ts": "0.85.0",
+    "openapi-typescript": "^7.9.1",
+    "vitest": "^3.2.4"
   },
-  "exports": {
-    ".": {
-      "import": {
-        "@s2-dev/streamstore/source": "./src/index.ts",
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/index.d.ts",
-        "default": "./dist/commonjs/index.js"
-      }
-    },
-    "./package.json": "./package.json",
-    "./types": {
-      "import": {
-        "@s2-dev/streamstore/source": "./src/types/index.ts",
-        "types": "./dist/esm/types/index.d.ts",
-        "default": "./dist/esm/types/index.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/types/index.d.ts",
-        "default": "./dist/commonjs/types/index.js"
-      }
-    },
-    "./models/errors": {
-      "import": {
-        "@s2-dev/streamstore/source": "./src/models/errors/index.ts",
-        "types": "./dist/esm/models/errors/index.d.ts",
-        "default": "./dist/esm/models/errors/index.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/models/errors/index.d.ts",
-        "default": "./dist/commonjs/models/errors/index.js"
-      }
-    },
-    "./models/components": {
-      "import": {
-        "@s2-dev/streamstore/source": "./src/models/components/index.ts",
-        "types": "./dist/esm/models/components/index.d.ts",
-        "default": "./dist/esm/models/components/index.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/models/components/index.d.ts",
-        "default": "./dist/commonjs/models/components/index.js"
-      }
-    },
-    "./models/operations": {
-      "import": {
-        "@s2-dev/streamstore/source": "./src/models/operations/index.ts",
-        "types": "./dist/esm/models/operations/index.d.ts",
-        "default": "./dist/esm/models/operations/index.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/models/operations/index.d.ts",
-        "default": "./dist/commonjs/models/operations/index.js"
-      }
-    },
-    "./*.js": {
-      "import": {
-        "@s2-dev/streamstore/source": "./src/*.ts",
-        "types": "./dist/esm/*.d.ts",
-        "default": "./dist/esm/*.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/*.d.ts",
-        "default": "./dist/commonjs/*.js"
-      }
-    },
-    "./*": {
-      "import": {
-        "@s2-dev/streamstore/source": "./src/*.ts",
-        "types": "./dist/esm/*.d.ts",
-        "default": "./dist/esm/*.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/*.d.ts",
-        "default": "./dist/commonjs/*.js"
-      }
-    }
+  "peerDependencies": {
+    "typescript": "^5.5"
   },
-  "main": "./dist/commonjs/index.js",
-  "types": "./dist/commonjs/index.d.ts",
-  "module": "./dist/esm/index.js"
+  "dependencies": {
+    "effect": "^3.18.4",
+    "js-base64": "^3.7.8",
+    "openapi-fetch": "^0.14.1"
+  }
 }

package/src/accessTokens.ts

@@ -0,0 +1,100 @@
+import type { DataToObject, S2RequestOptions } from "./common";
+import { S2Error } from "./error";
+import {
+	type IssueAccessTokenData,
+	issueAccessToken,
+	type ListAccessTokensData,
+	listAccessTokens,
+	type RevokeAccessTokenData,
+	revokeAccessToken,
+} from "./generated";
+import type { Client } from "./generated/client/types.gen";
+
+export interface ListAccessTokensArgs
+	extends DataToObject<ListAccessTokensData> {}
+export interface IssueAccessTokenArgs
+	extends DataToObject<IssueAccessTokenData> {}
+export interface RevokeAccessTokenArgs
+	extends DataToObject<RevokeAccessTokenData> {}
+
+export class S2AccessTokens {
+	readonly client: Client;
+
+	constructor(client: Client) {
+		this.client = client;
+	}
+
+	/**
+	 * List access tokens.
+	 *
+	 * @param args.prefix Filter to IDs beginning with this prefix
+	 * @param args.start_after Filter to IDs lexicographically after this value
+	 * @param args.limit Max results (up to 1000)
+	 */
+	public async list(args?: ListAccessTokensArgs, options?: S2RequestOptions) {
+		const response = await listAccessTokens({
+			client: this.client,
+			query: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+
+	/**
+	 * Issue a new access token.
+	 *
+	 * @param args.id Unique token ID (1-96 bytes)
+	 * @param args.scope Token scope (operations and resource sets)
+	 * @param args.auto_prefix_streams Namespace stream names by configured prefix scope
+	 * @param args.expires_at Expiration in ISO 8601; defaults to requestor's token expiry
+	 */
+	public async issue(args: IssueAccessTokenArgs, options?: S2RequestOptions) {
+		const response = await issueAccessToken({
+			client: this.client,
+			body: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+
+	/**
+	 * Revoke an access token by ID.
+	 *
+	 * @param args.id Token ID to revoke
+	 */
+	public async revoke(args: RevokeAccessTokenArgs, options?: S2RequestOptions) {
+		const response = await revokeAccessToken({
+			client: this.client,
+			path: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+}

package/src/basin.ts

@@ -0,0 +1,43 @@
+import { Redacted } from "effect";
+import { createClient, createConfig } from "./generated/client";
+import type { Client } from "./generated/client/types.gen";
+import { S2Stream } from "./stream";
+import { S2Streams } from "./streams";
+
+export class S2Basin {
+	private readonly client: Client;
+	private readonly accessToken: Redacted.Redacted;
+
+	public readonly name: string;
+	public readonly streams: S2Streams;
+
+	/**
+	 * Create a basin-scoped client that talks to `https://{basin}.b.aws.s2.dev/v1`.
+	 *
+	 * Use this to work with streams inside a single basin.
+	 * @param name Basin name
+	 * @param accessToken Redacted access token from the parent `S2` client
+	 */
+	constructor(
+		name: string,
+		options: { accessToken: Redacted.Redacted; baseUrl: string },
+	) {
+		this.name = name;
+		this.accessToken = options.accessToken;
+		this.client = createClient(
+			createConfig({
+				baseUrl: options.baseUrl,
+				auth: () => Redacted.value(this.accessToken),
+			}),
+		);
+		this.streams = new S2Streams(this.client);
+	}
+
+	/**
+	 * Create a stream-scoped helper bound to `this` basin.
+	 * @param name Stream name
+	 */
+	public stream(name: string) {
+		return new S2Stream(name, this.client);
+	}
+}

package/src/basins.ts

@@ -0,0 +1,154 @@
+import type { DataToObject, S2RequestOptions } from "./common";
+import { S2Error } from "./error";
+import {
+	type CreateBasinData,
+	createBasin,
+	type DeleteBasinData,
+	deleteBasin,
+	type GetBasinConfigData,
+	getBasinConfig,
+	type ListBasinsData,
+	listBasins,
+	type ReconfigureBasinData,
+	reconfigureBasin,
+} from "./generated";
+import type { Client } from "./generated/client/types.gen";
+
+export interface ListBasinsArgs extends DataToObject<ListBasinsData> {}
+export interface CreateBasinArgs extends DataToObject<CreateBasinData> {}
+export interface GetBasinConfigArgs extends DataToObject<GetBasinConfigData> {}
+export interface DeleteBasinArgs extends DataToObject<DeleteBasinData> {}
+export interface ReconfigureBasinArgs
+	extends DataToObject<ReconfigureBasinData> {}
+
+export class S2Basins {
+	private readonly client: Client;
+
+	constructor(client: Client) {
+		this.client = client;
+	}
+
+	/**
+	 * List basins.
+	 *
+	 * @param args.prefix Return basins whose names start with the given prefix
+	 * @param args.start_after Name to start after (for pagination)
+	 * @param args.limit Max results (up to 1000)
+	 */
+	public async list(args?: ListBasinsArgs, options?: S2RequestOptions) {
+		const response = await listBasins({
+			client: this.client,
+			query: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+
+	/**
+	 * Create a basin.
+	 *
+	 * @param args.basin Globally unique basin name (8-48 chars, lowercase letters, numbers, hyphens; cannot begin or end with a hyphen)
+	 * @param args.config Optional basin configuration (e.g. default stream config)
+	 * @param args.scope Basin scope
+	 */
+	public async create(args: CreateBasinArgs, options?: S2RequestOptions) {
+		const response = await createBasin({
+			client: this.client,
+			body: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+
+	/**
+	 * Get basin configuration.
+	 *
+	 * @param args.basin Basin name
+	 */
+	public async getConfig(args: GetBasinConfigArgs, options?: S2RequestOptions) {
+		const response = await getBasinConfig({
+			client: this.client,
+			path: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+
+	/**
+	 * Delete a basin.
+	 *
+	 * @param args.basin Basin name
+	 */
+	public async delete(args: DeleteBasinArgs, options?: S2RequestOptions) {
+		const response = await deleteBasin({
+			client: this.client,
+			path: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+
+	/**
+	 * Reconfigure a basin.
+	 *
+	 * @param args.basin Basin name
+	 * @param args.body Configuration fields to change (e.g. default stream config)
+	 */
+	public async reconfigure(
+		args: ReconfigureBasinArgs,
+		options?: S2RequestOptions,
+	) {
+		const response = await reconfigureBasin({
+			client: this.client,
+			path: args,
+			body: args,
+			...options,
+		});
+
+		if (response.error) {
+			throw new S2Error({
+				message: response.error.message,
+				code: response.error.code ?? undefined,
+				status: response.response.status,
+			});
+		}
+
+		return response.data;
+	}
+}