@s2-dev/streamstore 0.3.17 → 0.4.2

package/src/mcp-server/tools/streamRead.ts

@@ -0,0 +1,38 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { streamRead } from "../../funcs/streamRead.js";
+import * as operations from "../../models/operations/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: operations.ReadRequest$inboundSchema,
+};
+
+export const tool$streamRead: ToolDefinition<typeof args> = {
+  name: "stream_read",
+  description: `Retrieve records.
+
+Retrieve a batch of records, or set \`Accept: text/event-stream\` to stream using server-sent events.`,
+  scopes: ["read"],
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await streamRead(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools.ts

@@ -0,0 +1,116 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { objectOutputType, ZodRawShape, ZodTypeAny } from "zod";
+import { S2Core } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+import { isAsyncIterable, isBinaryData, valueToBase64 } from "./shared.js";
+
+export type ToolDefinition<Args extends undefined | ZodRawShape = undefined> =
+  Args extends ZodRawShape ? {
+      name: string;
+      description: string;
+      scopes?: MCPScope[];
+      args: Args;
+      tool: (
+        client: S2Core,
+        args: objectOutputType<Args, ZodTypeAny>,
+        extra: RequestHandlerExtra,
+      ) => CallToolResult | Promise<CallToolResult>;
+    }
+    : {
+      name: string;
+      description: string;
+      scopes?: MCPScope[];
+      args?: undefined;
+      tool: (
+        client: S2Core,
+        extra: RequestHandlerExtra,
+      ) => CallToolResult | Promise<CallToolResult>;
+    };
+
+export async function formatResult(
+  value: unknown,
+  init: { response?: Response | undefined },
+): Promise<CallToolResult> {
+  if (typeof value === "undefined") {
+    return { content: [] };
+  }
+
+  const { response } = init;
+  const contentType = response?.headers.get("content-type") ?? "";
+  let content: CallToolResult["content"] = [];
+
+  if (contentType.search(/\bjson\b/g)) {
+    content = [{ type: "text", text: JSON.stringify(value) }];
+  } else if (
+    contentType.startsWith("text/event-stream")
+    && isAsyncIterable(value)
+  ) {
+    content = await consumeSSE(value);
+  } else if (contentType.startsWith("text/") && typeof value === "string") {
+    content = [{ type: "text", text: value }];
+  } else if (isBinaryData(value) && contentType.startsWith("image/")) {
+    const data = await valueToBase64(value);
+    content = data == null
+      ? []
+      : [{ type: "image", data, mimeType: contentType }];
+  } else {
+    return {
+      content: [{
+        type: "text",
+        text: `Unsupported content type: "${contentType}"`,
+      }],
+      isError: true,
+    };
+  }
+
+  return { content };
+}
+
+async function consumeSSE(
+  value: AsyncIterable<unknown>,
+): Promise<CallToolResult["content"]> {
+  const content: CallToolResult["content"] = [];
+
+  for await (const chunk of value) {
+    if (typeof chunk === "string") {
+      content.push({ type: "text", text: chunk });
+    } else {
+      content.push({ type: "text", text: JSON.stringify(chunk) });
+    }
+  }
+
+  return content;
+}
+
+export function createRegisterTool(
+  logger: ConsoleLogger,
+  server: McpServer,
+  sdk: S2Core,
+  allowedScopes: Set<MCPScope>,
+): <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>) => void {
+  return <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>): void => {
+    const toolScopes = tool.scopes ?? [];
+    if (!toolScopes.every((s) => allowedScopes.has(s))) {
+      return;
+    }
+
+    if (tool.args) {
+      server.tool(tool.name, tool.description, tool.args, async (args, ctx) => {
+        return tool.tool(sdk, args, ctx);
+      });
+    } else {
+      server.tool(tool.name, tool.description, async (ctx) => {
+        return tool.tool(sdk, ctx);
+      });
+    }
+
+    logger.debug("Registered tool", { name: tool.name });
+  };
+}

package/src/models/components/endpoints.ts

@@ -0,0 +1,159 @@
+type Authority = string;
+
+// Basin Name
+type BasinName = string;
+
+/**
+ * S2 cloud environment to connect with.
+ */
+export enum S2Cloud {
+    /** S2 running on AWS */
+    Aws = "aws"
+}
+
+/**
+ * Endpoint for connecting to an S2 basin.
+ */
+export enum BasinEndpointKind {
+    ParentZone = "ParentZone",
+    Direct = "Direct"
+}
+
+export type BasinEndpoint = {
+    kind: BasinEndpointKind.ParentZone;
+    authority: Authority;
+} | {
+    kind: BasinEndpointKind.Direct;
+    authority: Authority;
+};
+
+class S2EndpointError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'S2EndpointError';
+    }
+}
+
+/**
+ * Endpoints for the S2 environment.
+ * 
+ * You can find the S2 endpoints in our [documentation](https://s2.dev/docs/interface/endpoints)
+ */
+export class S2Endpoints {
+    /** Used by `AccountService` requests */
+    public account: Authority;
+    /** Used by `BasinService` and `StreamService` requests */
+    public basin: BasinEndpoint;
+
+    constructor(account: Authority, basin: BasinEndpoint) {
+        this.account = account;
+        this.basin = basin;
+    }
+
+    /**
+     * Get S2 endpoints for the specified cloud.
+     */
+    static forCloud(cloud: S2Cloud): S2Endpoints {
+        const authority = `${cloud}.s2.dev`;
+        return new S2Endpoints(
+            authority,
+            {
+                kind: BasinEndpointKind.ParentZone,
+                authority: `b.${cloud}.s2.dev`
+            }
+        );
+    }
+
+    /**
+     * Get S2 endpoints for the specified cell.
+     */
+    static forCell(cloud: S2Cloud, cellId: string): S2Endpoints {
+        const cellEndpoint = `${cellId}.o.${cloud}.s2.dev`;
+        return new S2Endpoints(
+            cellEndpoint,
+            {
+                kind: BasinEndpointKind.Direct,
+                authority: cellEndpoint
+            }
+        );
+    }
+
+    /**
+     * Get S2 endpoints from environment variables.
+     * 
+     * The following environment variables are used:
+     * - `S2_CLOUD`: Valid S2 cloud name. Defaults to AWS.
+     * - `S2_ACCOUNT_ENDPOINT`: Overrides the account endpoint.
+     * - `S2_BASIN_ENDPOINT`: Overrides the basin endpoint. The prefix `"{basin}."` indicates the
+     *   basin endpoint is `ParentZone` else `Direct`.
+     */
+    static fromEnv(): S2Endpoints {
+        let cloud: S2Cloud;
+        try {
+            const cloudEnv = process.env['S2_CLOUD'] || S2Cloud.Aws;
+            if (Object.values(S2Cloud).includes(cloudEnv as S2Cloud)) {
+                cloud = cloudEnv as S2Cloud;
+            } else {
+                throw new S2EndpointError(`Invalid S2_CLOUD: ${cloudEnv}`);
+            }
+        } catch (err) {
+            const error = err as Error;
+            throw new S2EndpointError(`Invalid S2_CLOUD: ${error.message}`);
+        }
+
+        const endpoints = S2Endpoints.forCloud(cloud);
+
+        const accountEndpoint = process.env['S2_ACCOUNT_ENDPOINT'];
+        if (accountEndpoint !== undefined) {
+            if (typeof accountEndpoint !== 'string') {
+                throw new S2EndpointError('Invalid S2_ACCOUNT_ENDPOINT: not string');
+            }
+            endpoints.account = accountEndpoint;
+        }
+
+        const basinEndpoint = process.env['S2_BASIN_ENDPOINT'];
+        if (basinEndpoint !== undefined) {
+            if (typeof basinEndpoint !== 'string') {
+                throw new S2EndpointError('Invalid S2_BASIN_ENDPOINT: not string');
+            }
+
+            if (basinEndpoint.startsWith('{basin}.')) {
+                const parentZone = basinEndpoint.substring(7);
+                endpoints.basin = {
+                    kind: BasinEndpointKind.ParentZone,
+                    authority: parentZone
+                };
+            } else {
+                endpoints.basin = {
+                    kind: BasinEndpointKind.Direct,
+                    authority: basinEndpoint
+                };
+            }
+        }
+
+        return endpoints;
+    }
+}
+
+/**
+ * Client kind for different S2 services
+ */
+export type ClientKind = 
+    | { kind: 'Account' }
+    | { kind: 'Basin'; basin: BasinName };
+
+export const ClientKind = {
+    toAuthority(kind: ClientKind, endpoints: S2Endpoints): Authority {
+        switch (kind.kind) {
+            case 'Account':
+                return endpoints.account;
+            case 'Basin':
+                switch (endpoints.basin.kind) {
+                    case BasinEndpointKind.ParentZone:
+                        return `${kind.basin}.${endpoints.basin.authority}`;
+                    case BasinEndpointKind.Direct:
+                        return endpoints.basin.authority;
+                }
+        }
+    }
+};

package/src/types/async.ts

@@ -0,0 +1,68 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export type APICall =
+  | {
+      status: "complete";
+      request: Request;
+      response: Response;
+    }
+  | {
+      status: "request-error";
+      request: Request;
+      response?: undefined;
+    }
+  | {
+      status: "invalid";
+      request?: undefined;
+      response?: undefined;
+    };
+
+export class APIPromise<T> implements Promise<T> {
+  readonly #promise: Promise<[T, APICall]>;
+  readonly #unwrapped: Promise<T>;
+
+  readonly [Symbol.toStringTag] = "APIPromise";
+
+  constructor(p: [T, APICall] | Promise<[T, APICall]>) {
+    this.#promise = p instanceof Promise ? p : Promise.resolve(p);
+    this.#unwrapped =
+      p instanceof Promise
+        ? this.#promise.then(([value]) => value)
+        : Promise.resolve(p[0]);
+  }
+
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?:
+      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+      | null
+      | undefined,
+    onrejected?:
+      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | null
+      | undefined,
+  ): Promise<TResult1 | TResult2> {
+    return this.#promise.then(
+      onfulfilled ? ([value]) => onfulfilled(value) : void 0,
+      onrejected,
+    );
+  }
+
+  catch<TResult = never>(
+    onrejected?:
+      | ((reason: any) => TResult | PromiseLike<TResult>)
+      | null
+      | undefined,
+  ): Promise<T | TResult> {
+    return this.#unwrapped.catch(onrejected);
+  }
+
+  finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+    return this.#unwrapped.finally(onfinally);
+  }
+
+  $inspect(): Promise<[T, APICall]> {
+    return this.#promise;
+  }
+}

package/types/async.d.ts

@@ -0,0 +1,23 @@
+export type APICall = {
+    status: "complete";
+    request: Request;
+    response: Response;
+} | {
+    status: "request-error";
+    request: Request;
+    response?: undefined;
+} | {
+    status: "invalid";
+    request?: undefined;
+    response?: undefined;
+};
+export declare class APIPromise<T> implements Promise<T> {
+    #private;
+    readonly [Symbol.toStringTag] = "APIPromise";
+    constructor(p: [T, APICall] | Promise<[T, APICall]>);
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    $inspect(): Promise<[T, APICall]>;
+}
+//# sourceMappingURL=async.d.ts.map

package/types/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../src/types/async.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,OAAO,GACf;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACpB,GACD;IACE,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAEN,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,OAAO,CAAC,CAAC,CAAC;;IAI9C,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,gBAAgB;gBAEjC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAQnD,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK,EACjC,WAAW,CAAC,EACR,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAChD,IAAI,GACJ,SAAS,EACb,UAAU,CAAC,EACP,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GACnD,IAAI,GACJ,SAAS,GACZ,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAO/B,KAAK,CAAC,OAAO,GAAG,KAAK,EACnB,UAAU,CAAC,EACP,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GACjD,IAAI,GACJ,SAAS,GACZ,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC;IAIvB,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhE,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;CAGlC"}

package/types/async.js

@@ -0,0 +1,44 @@
+"use strict";
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _APIPromise_promise, _APIPromise_unwrapped, _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIPromise = void 0;
+class APIPromise {
+    constructor(p) {
+        _APIPromise_promise.set(this, void 0);
+        _APIPromise_unwrapped.set(this, void 0);
+        this[_a] = "APIPromise";
+        __classPrivateFieldSet(this, _APIPromise_promise, p instanceof Promise ? p : Promise.resolve(p), "f");
+        __classPrivateFieldSet(this, _APIPromise_unwrapped, p instanceof Promise
+            ? __classPrivateFieldGet(this, _APIPromise_promise, "f").then(([value]) => value)
+            : Promise.resolve(p[0]), "f");
+    }
+    then(onfulfilled, onrejected) {
+        return __classPrivateFieldGet(this, _APIPromise_promise, "f").then(onfulfilled ? ([value]) => onfulfilled(value) : void 0, onrejected);
+    }
+    catch(onrejected) {
+        return __classPrivateFieldGet(this, _APIPromise_unwrapped, "f").catch(onrejected);
+    }
+    finally(onfinally) {
+        return __classPrivateFieldGet(this, _APIPromise_unwrapped, "f").finally(onfinally);
+    }
+    $inspect() {
+        return __classPrivateFieldGet(this, _APIPromise_promise, "f");
+    }
+}
+exports.APIPromise = APIPromise;
+_APIPromise_promise = new WeakMap(), _APIPromise_unwrapped = new WeakMap(), _a = Symbol.toStringTag;
+//# sourceMappingURL=async.js.map

package/types/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../src/types/async.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;AAmBH,MAAa,UAAU;IAMrB,YAAY,CAAuC;QAL1C,sCAAgC;QAChC,wCAAuB;QAEvB,QAAoB,GAAG,YAAY,CAAC;QAG3C,uBAAA,IAAI,uBAAY,CAAC,YAAY,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAA,CAAC;QAC9D,uBAAA,IAAI,yBACF,CAAC,YAAY,OAAO;YAClB,CAAC,CAAC,uBAAA,IAAI,2BAAS,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC;YACxC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAA,CAAC;IAC9B,CAAC;IAED,IAAI,CACF,WAGa,EACb,UAGa;QAEb,OAAO,uBAAA,IAAI,2BAAS,CAAC,IAAI,CACvB,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EACtD,UAAU,CACX,CAAC;IACJ,CAAC;IAED,KAAK,CACH,UAGa;QAEb,OAAO,uBAAA,IAAI,6BAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,CAAC,SAA2C;QACjD,OAAO,uBAAA,IAAI,6BAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED,QAAQ;QACN,OAAO,uBAAA,IAAI,2BAAS,CAAC;IACvB,CAAC;CACF;AA9CD,gCA8CC;iFA1CW,MAAM,CAAC,WAAW"}