@s2-dev/streamstore 0.3.14 → 0.4.2

package/src/index.extras.ts

@@ -75,8 +75,29 @@ export type S2ClientConfig = {
     httpClient?: HTTPClient;
 };
 
+/**
+ * Override the client level configuration for a specific operation.
+ *
+ * @remarks
+ * Only `authToken` can be overridden for now.
+ */
+export type S2OperationConfig = {
+    authToken?: string;
+};
+
+/**
+ * Retry policy for appends.
+ */
 export enum AppendRetryPolicy {
+    /**
+     * Retry all eligible failures encountered during an append.
+     * This could result in append batches being duplicated on the stream.     
+     */
     All,
+    /**
+     * Retry only failures with no side effects.
+     * Will not attempt to retry failures where it cannot be concluded whether an append may become durable, in order to prevent duplicates.
+     */
     NoSideEffects,
 }
 
@@ -92,12 +113,9 @@ const defaultS2ClientConfig: S2ClientConfig = {
 
 export class S2Client {
     private config: S2ClientConfig;
-    private _account?: S2Account;    
+    private _account?: S2Account;
 
     get account(): S2Account {
-        // this.httpClient.addHook("beforeRequest", (request) => {
-        //     if (this.config.userAgent) request.headers.set("User-Agent", this.config.userAgent);
-        // });
         return (this._account ??= new S2Account(this.config));
     }
 
@@ -117,12 +135,11 @@ class S2Account {
     private readonly accountURLSuffx = "/v1alpha";
 
     constructor(config: S2ClientConfig) {
-        if (config.userAgent !== undefined) {
-            config.httpClient?.addHook("beforeRequest", (request) => {
+        config.httpClient?.addHook("beforeRequest", (request) => {
+            if (config.userAgent !== undefined) {
                 request.headers.set("user-agent", config.userAgent ?? "s2-sdk-typescript");
-                console.log(request)
-            });
-        }
+            }
+        });
         this._account = new InnerAccount({
             ...(config.authToken !== undefined && { bearerAuth: config.authToken }),
             ...(config.requestTimeout !== undefined && { timeoutMs: config.requestTimeout }),
@@ -131,57 +148,67 @@ class S2Account {
         this.config = config;
     }
 
-    get URL(): string | undefined {
-        if (!this.config.endpoints) return undefined;
-        return `https://${ClientKind.toAuthority({ kind: "Account" }, this.config.endpoints)}${this.accountURLSuffx}`;
-    }    
+    get URL(): string {
+        return `https://${ClientKind.toAuthority({ kind: "Account" }, this.config.endpoints ?? S2Endpoints.forCloud(S2Cloud.Aws))}${this.accountURLSuffx}`;
+    }
 
     basin(basinName: string): S2Basin {
         return new S2Basin(basinName, this.config);
     }
 
+    private overrideConfig(config?: S2OperationConfig) {
+        this.config.httpClient?.addHook("beforeRequest", (request) => {
+            if (config?.authToken !== undefined) {
+                request.headers.set("Authorization", `Bearer ${config.authToken}`);
+            }            
+        });
+    }
+
     async listBasins(
-        request?: ListBasinsRequest
+        request?: ListBasinsRequest,
+        opConfig?: S2OperationConfig,
     ): Promise<PageIterator<ListBasinsResponse, { cursor: string }>> {
-        const url = this.URL;
+        this.overrideConfig(opConfig);
         return retryWithExponentialBackoff(
-            () => this._account.listBasins(request ?? {}, url ? { serverURL: url } : {}),
+            () => this._account.listBasins(request ?? {}, {
+                serverURL: this.URL,
+            }),
             this.config.maxRetries,
             this.config.initialBackoffMs,
             this.config.maxBackoffMs
         );
     }
 
-    async getBasinConfig(basin: string): Promise<BasinConfig | undefined> {
+    async getBasinConfig(basin: string, opConfig?: S2OperationConfig): Promise<BasinConfig | undefined> {
+        this.overrideConfig(opConfig);
         const _request: GetBasinConfigRequest = { basin };
-        const url = this.URL;
         return retryWithExponentialBackoff(
-            () => this._account.getBasinConfig(_request, url ? { serverURL: url } : {}),
+            () => this._account.getBasinConfig(_request, { serverURL: this.URL }),
             this.config.maxRetries,
             this.config.initialBackoffMs,
             this.config.maxBackoffMs
         );
     }
 
-    async createBasin(basin: string, request?: CreateBasinRequest): Promise<BasinInfo | undefined> {
+    async createBasin(basin: string, request?: CreateBasinRequest, opConfig?: S2OperationConfig): Promise<BasinInfo | undefined> {
+        this.overrideConfig(opConfig);
         const _request: CreateBasinRequestInner = {
             basin,
             s2RequestToken: genS2RequestToken(),
             createBasinRequest: request ?? {},
         };
-        const url = this.URL;
         return retryWithExponentialBackoff(
-            () => this._account.createBasin(_request, url ? { serverURL: url } : {}),
+            () => this._account.createBasin(_request, { serverURL: this.URL }),
             this.config.maxRetries,
             this.config.initialBackoffMs,
             this.config.maxBackoffMs
         );
     }
 
-    async deleteBasin(basin: string, if_exists?: boolean): Promise<void> {
-        const url = this.URL;
+    async deleteBasin(basin: string, if_exists?: boolean, opConfig?: S2OperationConfig): Promise<void> {
+        this.overrideConfig(opConfig);
         const response = await retryWithExponentialBackoff(
-            () => accountDeleteBasin(this._account, { basin }, url ? { serverURL: url } : {}),
+            () => accountDeleteBasin(this._account, { basin }, { serverURL: this.URL }),
             this.config.maxRetries,
             this.config.initialBackoffMs,
             this.config.maxBackoffMs
@@ -191,11 +218,11 @@ class S2Account {
         return;
     }
 
-    async reconfigureBasin(basin: string, config: BasinConfig): Promise<BasinConfig | undefined> {
-        const url = this.URL;
+    async reconfigureBasin(basin: string, config: BasinConfig, opConfig?: S2OperationConfig): Promise<BasinConfig | undefined> {
+        this.overrideConfig(opConfig);
         const _request: ReconfigureBasinRequest = { basin, basinConfig: config };
         return retryWithExponentialBackoff(
-            () => this._account.reconfigureBasin(_request, url ? { serverURL: url } : {}),
+            () => this._account.reconfigureBasin(_request, { serverURL: this.URL }),
             this.config.maxRetries,
             this.config.initialBackoffMs,
             this.config.maxBackoffMs
@@ -209,21 +236,25 @@ class S2Basin {
     private basinName: string;
     private config: S2ClientConfig;
     private clientKind: ClientKind;
-    private readonly basinURLSuffx = "/v1alpha";    
+    private readonly basinURLSuffx = "/v1alpha";
 
     private get URL(): string {
         return `https://${ClientKind.toAuthority(this.clientKind, this.config.endpoints ?? S2Endpoints.forCloud(S2Cloud.Aws))}${this.basinURLSuffx}`;
     }
 
     constructor(basinName: string, config: S2ClientConfig) {
-        if (config.userAgent !== undefined) {
-            config.httpClient?.addHook("beforeRequest", (request) => {
+        config.httpClient?.addHook("beforeRequest", (request) => {
+            if (config.userAgent !== undefined) {
                 request.headers.set("user-agent", config.userAgent ?? "s2-sdk-typescript");
-            });
-        }
+            }
+            if (config.endpoints?.basin?.kind === "Direct") {
+                request.headers.set("s2-basin", basinName);
+            }
+        });
         this._basin = new InnerBasin({
             ...(config.authToken !== undefined && { bearerAuth: config.authToken }),
-            ...(config.requestTimeout !== undefined && { timeoutMs: config.requestTimeout })
+            ...(config.requestTimeout !== undefined && { timeoutMs: config.requestTimeout }),
+            ...(config.httpClient !== undefined && { httpClient: config.httpClient }),
         });
         this.config = config;
         this.clientKind = { kind: "Basin" as const, basin: basinName };
@@ -234,18 +265,32 @@ class S2Basin {
         return (this._stream ??= new Stream(this.basinName, streamName, this.config));
     }
 
+    private overrideConfig(config?: S2OperationConfig) {
+        this.config.httpClient?.addHook("beforeRequest", (request) => {
+            if (config?.authToken !== undefined) {
+                request.headers.set("Authorization", `Bearer ${config.authToken}`);
+            }            
+        });
+    }
+
     async listStreams(
-        request: ListStreamsRequest
+        request?: ListStreamsRequest,
+        opConfig?: S2OperationConfig,
     ): Promise<PageIterator<ListStreamsResponse, { cursor: string }>> {
+        this.overrideConfig(opConfig);
         return retryWithExponentialBackoff(
-            () => this._basin.listStreams(request, { serverURL: this.URL }),
+            () => this._basin.listStreams(request ?? {}, { serverURL: this.URL }),
             this.config.maxRetries,
             this.config.initialBackoffMs,
             this.config.maxBackoffMs
         );
     }
 
-    async getStreamConfig(stream: string): Promise<StreamConfig | undefined> {
+    async getStreamConfig(
+        stream: string,
+        opConfig?: S2OperationConfig
+    ): Promise<StreamConfig | undefined> {
+        this.overrideConfig(opConfig);
         return retryWithExponentialBackoff(
             () => this._basin.getStreamConfig({ stream }, { serverURL: this.URL }),
             this.config.maxRetries,
@@ -254,7 +299,8 @@ class S2Basin {
         );
     }
 
-    async createStream(stream: string, request?: CreateStreamRequest): Promise<StreamInfo | undefined> {
+    async createStream(stream: string, request?: CreateStreamRequest, opConfig?: S2OperationConfig): Promise<StreamInfo | undefined> {
+        this.overrideConfig(opConfig);
         const _request: CreateStreamRequestInner = {
             stream,
             s2RequestToken: genS2RequestToken(),
@@ -268,7 +314,8 @@ class S2Basin {
         );
     }
 
-    async deleteStream(stream: string, if_exists?: boolean): Promise<void | undefined> {
+    async deleteStream(stream: string, if_exists?: boolean, opConfig?: S2OperationConfig): Promise<void | undefined> {
+        this.overrideConfig(opConfig);
         const response = await retryWithExponentialBackoff(
             () => basinDeleteStream(this._basin, { stream }, { serverURL: this.URL }),
             this.config.maxRetries,
@@ -280,7 +327,8 @@ class S2Basin {
         return;
     }
 
-    async reconfigureStream(stream: string, config: StreamConfig): Promise<StreamConfig> {
+    async reconfigureStream(stream: string, config: StreamConfig, opConfig?: S2OperationConfig): Promise<StreamConfig> {
+        this.overrideConfig(opConfig);
         return retryWithExponentialBackoff(
             () => this._basin.reconfigureStream({ stream, streamConfig: config }, { serverURL: this.URL }),
             this.config.maxRetries,
@@ -301,28 +349,42 @@ class Stream {
         return `https://${ClientKind.toAuthority(this.clientKind, this.config.endpoints ?? S2Endpoints.forCloud(S2Cloud.Aws))}${this.basinURLSuffx}`;
     }
 
+    private overrideConfig(config?: S2OperationConfig) {
+        this.config.httpClient?.addHook("beforeRequest", (request) => {
+            if (config?.authToken !== undefined) {
+                request.headers.set("Authorization", `Bearer ${config.authToken}`);
+            }            
+        });
+    }
+
     constructor(basinName: string, streamName: string, config: S2ClientConfig) {
         this.config = config;
         this.clientKind = { kind: "Basin" as const, basin: basinName };
         this.streamName = streamName;
-        if (config.userAgent !== undefined) {
-            config.httpClient?.addHook("beforeRequest", (request) => {
+        config.httpClient?.addHook("beforeRequest", (request) => {
+            if (config.userAgent !== undefined) {
                 request.headers.set("user-agent", config.userAgent ?? "s2-sdk-typescript");
-            });
-        }
+            }
+            if (config.endpoints?.basin?.kind === "Direct") {
+                request.headers.set("s2-basin", basinName);
+            }
+        });
         this._stream = new InnerStream({
             ...(config.authToken !== undefined && { bearerAuth: config.authToken }),
-            ...(config.requestTimeout !== undefined && { timeoutMs: config.requestTimeout })
+            ...(config.requestTimeout !== undefined && { timeoutMs: config.requestTimeout }),
+            ...(config.httpClient !== undefined && { httpClient: config.httpClient })
         });
     }
 
-    async checkTail(): Promise<CheckTailResponse> {
+    async checkTail(opConfig?: S2OperationConfig): Promise<CheckTailResponse> {
+        this.overrideConfig(opConfig);
         return (
             await this._stream.checkTail({ stream: this.streamName }, { serverURL: this.basinURL })
         );
     }
 
-    async append(request: AppendRequest): Promise<AppendOutput> {
+    async append(request: AppendRequest, opConfig?: S2OperationConfig): Promise<AppendOutput> {
+        this.overrideConfig(opConfig);
         switch (this.config.appedRetryPolicy) {
             case AppendRetryPolicy.All:
             case undefined:
@@ -343,13 +405,15 @@ class Stream {
         }
     }
 
-    async read(request: ReadRequest): Promise<Output> {
+    async read(request: ReadRequest, opConfig?: S2OperationConfig): Promise<Output> {
+        this.overrideConfig(opConfig);
         return (
             await this._stream.read({ ...request, stream: this.streamName }, { serverURL: this.basinURL }) as Output
         );
     }
 
-    async *readStream(request: ReadRequest): AsyncGenerator<ReadResponse, void, undefined> {
+    async *readStream(request: ReadRequest, opConfig?: S2OperationConfig): AsyncGenerator<ReadResponse, void, undefined> {
+        this.overrideConfig(opConfig);
         let currentRequest: ReadRequest = { ...request };
         let initialBackoffMs = this.config.initialBackoffMs ?? 100;
         const maxBackoffMs = 5000;

package/src/lib/config.ts

@@ -15,17 +15,17 @@ export const ServerList = [
 ] as const;
 
 export type SDKOptions = {
-  bearerAuth?: string | (() => Promise<string>);
+  bearerAuth?: string | (() => Promise<string>) | undefined;
 
   httpClient?: HTTPClient;
   /**
    * Allows overriding the default server used by the SDK
    */
-  serverIdx?: number;
+  serverIdx?: number | undefined;
   /**
    * Allows overriding the default server URL used by the SDK
    */
-  serverURL?: string;
+  serverURL?: string | undefined;
   /**
    * Allows overriding the default retry config used by the SDK
    */
@@ -54,8 +54,7 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "1.0.0",
-  sdkVersion: "0.3.14",
-  genVersion: "2.506.0",
-  userAgent:
-    "speakeasy-sdk/typescript 0.3.14 2.506.0 1.0.0 @s2-dev/streamstore",
+  sdkVersion: "0.4.2",
+  genVersion: "2.529.2",
+  userAgent: "speakeasy-sdk/typescript 0.4.2 2.529.2 1.0.0 @s2-dev/streamstore",
 } as const;

package/src/lib/files.ts

@@ -36,5 +36,5 @@ export async function readableStreamToArrayBuffer(
     offset += chunk.length;
   }
 
-  return concatenatedChunks.buffer;
+  return concatenatedChunks.buffer as ArrayBuffer;
 }

package/src/lib/primitives.ts

@@ -134,3 +134,17 @@ export function compactMap<T>(
 
   return out;
 }
+
+export function allRequired<V extends Record<string, unknown>>(
+  v: V,
+):
+  | {
+      [K in keyof V]: NonNullable<V[K]>;
+    }
+  | undefined {
+  if (Object.values(v).every((x) => x == null)) {
+    return void 0;
+  }
+
+  return v as ReturnType<typeof allRequired<V>>;
+}

package/src/lib/sdks.ts

@@ -79,7 +79,7 @@ export class ClientSDK {
   readonly #httpClient: HTTPClient;
   readonly #hooks: SDKHooks;
   readonly #logger?: Logger | undefined;
-  protected readonly _baseURL: URL | null;
+  public readonly _baseURL: URL | null;
   public readonly _options: SDKOptions & { hooks?: SDKHooks };
 
   constructor(options: SDKOptions = {}) {

package/src/lib/security.ts

@@ -4,7 +4,6 @@
 
 import * as components from "../models/components/index.js";
 import { env } from "./env.js";
-
 type OAuth2PasswordFlow = {
   username: string;
   password?: string | undefined;

package/src/mcp-server/cli/start/command.ts

@@ -0,0 +1,98 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { buildCommand } from "@stricli/core";
+import { numberParser } from "@stricli/core";
+import * as z from "zod";
+import { consoleLoggerLevels } from "../../console-logger.js";
+import { mcpScopes } from "../../scopes.js";
+
+export const startCommand = buildCommand({
+  loader: async () => {
+    const { main } = await import("./impl.js");
+    return main;
+  },
+  parameters: {
+    flags: {
+      transport: {
+        kind: "enum",
+        brief: "The transport to use for communicating with the server",
+        default: "stdio",
+        values: ["stdio", "sse"],
+      },
+      port: {
+        kind: "parsed",
+        brief: "The port to use when the SSE transport is enabled",
+        default: "2718",
+        parse: (val: string) =>
+          z.coerce.number().int().gte(0).lt(65536).parse(val),
+      },
+      ...(mcpScopes.length
+        ? {
+          scope: {
+            kind: "enum",
+            brief:
+              "Mount tools/resources that match given scope (repeatable flag)",
+            values: mcpScopes,
+            variadic: true,
+            optional: true,
+          },
+        }
+        : {}),
+      "bearer-auth": {
+        kind: "parsed",
+        brief: "Sets the bearerAuth auth field for the API",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "server-url": {
+        kind: "parsed",
+        brief: "Overrides the default server URL used by the SDK",
+        optional: true,
+        parse: (value) => new URL(value).toString(),
+      },
+      "server-index": {
+        kind: "parsed",
+        brief: "Selects a predefined server used by the SDK",
+        optional: true,
+        parse: numberParser,
+      },
+      "log-level": {
+        kind: "enum",
+        brief: "The log level to use for the server",
+        default: "info",
+        values: consoleLoggerLevels,
+      },
+      env: {
+        kind: "parsed",
+        brief: "Environment variables made available to the server",
+        optional: true,
+        variadic: true,
+        parse: (val: string) => {
+          const sepIdx = val.indexOf("=");
+          if (sepIdx === -1) {
+            throw new Error("Invalid environment variable format");
+          }
+
+          const key = val.slice(0, sepIdx);
+          const value = val.slice(sepIdx + 1);
+
+          return [
+            z.string().nonempty({
+              message: "Environment variable key must be a non-empty string",
+            }).parse(key),
+            z.string().nonempty({
+              message: "Environment variable value must be a non-empty string",
+            }).parse(value),
+          ] satisfies [string, string];
+        },
+      },
+    },
+  },
+  docs: {
+    brief: "Run the Model Context Protocol server",
+  },
+});

package/src/mcp-server/cli/start/impl.ts

@@ -0,0 +1,131 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import express from "express";
+import { SDKOptions } from "../../../lib/config.js";
+import { LocalContext } from "../../cli.js";
+import {
+  ConsoleLoggerLevel,
+  createConsoleLogger,
+} from "../../console-logger.js";
+import { MCPScope } from "../../scopes.js";
+import { createMCPServer } from "../../server.js";
+
+interface StartCommandFlags {
+  readonly transport: "stdio" | "sse";
+  readonly port: number;
+  readonly scope?: MCPScope[];
+  readonly "bearer-auth"?: string | undefined;
+  readonly "server-url"?: string;
+  readonly "server-index"?: SDKOptions["serverIdx"];
+  readonly "log-level": ConsoleLoggerLevel;
+  readonly env?: [string, string][];
+}
+
+export async function main(this: LocalContext, flags: StartCommandFlags) {
+  flags.env?.forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  switch (flags.transport) {
+    case "stdio":
+      await startStdio(flags);
+      break;
+    case "sse":
+      await startSSE(flags);
+      break;
+    default:
+      throw new Error(`Invalid transport: ${flags.transport}`);
+  }
+}
+
+async function startStdio(flags: StartCommandFlags) {
+  const logger = createConsoleLogger(flags["log-level"]);
+  const transport = new StdioServerTransport();
+  const server = createMCPServer({
+    logger,
+    scopes: flags.scope,
+    ...{ bearerAuth: flags["bearer-auth"] },
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+  });
+  await server.connect(transport);
+
+  const abort = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}
+
+async function startSSE(flags: StartCommandFlags) {
+  const logger = createConsoleLogger(flags["log-level"]);
+  const app = express();
+  const mcpServer = createMCPServer({
+    logger,
+    scopes: flags.scope,
+    ...{ bearerAuth: flags["bearer-auth"] },
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+  });
+  let transport: SSEServerTransport | undefined;
+  const controller = new AbortController();
+
+  app.get("/sse", async (_req, res) => {
+    transport = new SSEServerTransport("/message", res);
+
+    await mcpServer.connect(transport);
+
+    mcpServer.server.onclose = async () => {
+      res.end();
+    };
+  });
+
+  app.post("/message", async (req, res) => {
+    if (!transport) {
+      throw new Error("Server transport not initialized");
+    }
+
+    await transport.handlePostMessage(req, res);
+  });
+
+  const httpServer = app.listen(flags.port, "0.0.0.0", () => {
+    const ha = httpServer.address();
+    const host = typeof ha === "string" ? ha : `${ha?.address}:${ha?.port}`;
+    logger.info("MCP HTTP server started", { host });
+  });
+
+  let closing = false;
+  controller.signal.addEventListener("abort", async () => {
+    if (closing) {
+      logger.info("Received second signal. Forcing shutdown.");
+      process.exit(1);
+    }
+    closing = true;
+
+    logger.info("Shutting down MCP server");
+
+    await mcpServer.close();
+
+    logger.info("Shutting down HTTP server");
+
+    const timer = setTimeout(() => {
+      logger.info("Forcing shutdown");
+      process.exit(1);
+    }, 5000);
+
+    httpServer.close(() => {
+      clearTimeout(timer);
+      logger.info("Graceful shutdown complete");
+      process.exit(0);
+    });
+  });
+
+  const abort = () => controller.abort();
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}

package/src/mcp-server/cli.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { CommandContext, StricliProcess } from "@stricli/core";
+
+export interface LocalContext extends CommandContext {
+  readonly process: StricliProcess;
+}
+
+export function buildContext(process: NodeJS.Process): LocalContext {
+  return { process: process as StricliProcess };
+}