@s2-dev/streamstore 0.8.2 → 0.9.0

package/src/mcp-server/prompts.ts

@@ -0,0 +1,110 @@
+/*
+ * 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 { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
+import {
+  objectOutputType,
+  ZodOptional,
+  ZodType,
+  ZodTypeAny,
+  ZodTypeDef,
+} from "zod";
+import { S2Core } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+
+// '@modelcontextprotocol/sdk' currently does not export this type
+export type PromptArgsRawShape = {
+  [k: string]:
+    | ZodType<string, ZodTypeDef, string>
+    | ZodOptional<ZodType<string, ZodTypeDef, string>>;
+};
+
+export type PromptDefinition<
+  Args extends undefined | PromptArgsRawShape = undefined,
+> = Args extends PromptArgsRawShape ? {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args: Args;
+    prompt: (
+      client: S2Core,
+      args: objectOutputType<Args, ZodTypeAny>,
+      extra: RequestHandlerExtra,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  }
+  : {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args?: undefined;
+    prompt: (
+      client: S2Core,
+      extra: RequestHandlerExtra,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  };
+
+// Optional function to assist with formatting prompt results
+export async function formatResult(value: string): Promise<GetPromptResult> {
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: value,
+        },
+      },
+    ],
+  };
+}
+
+export function createRegisterPrompt(
+  logger: ConsoleLogger,
+  server: McpServer,
+  sdk: S2Core,
+  allowedScopes: Set<MCPScope>,
+): <A extends PromptArgsRawShape | undefined>(
+  prompt: PromptDefinition<A>,
+) => void {
+  return <A extends PromptArgsRawShape | undefined>(
+    prompt: PromptDefinition<A>,
+  ): void => {
+    const scopes = prompt.scopes ?? [];
+    if (!scopes.every((s: MCPScope) => allowedScopes.has(s))) {
+      return;
+    }
+
+    if (prompt.args) {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(sdk, args, ctx),
+        );
+      } else {
+        server.prompt(
+          prompt.name,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(sdk, args, ctx),
+        );
+      }
+    } else {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          async (ctx) => prompt.prompt(sdk, ctx),
+        );
+      } else {
+        server.prompt(prompt.name, async (ctx) => prompt.prompt(sdk, ctx));
+      }
+    }
+
+    logger.debug("Registered prompt", { name: prompt.name });
+  };
+}

package/src/mcp-server/resources.ts

@@ -46,6 +46,7 @@ export type ResourceTemplateDefinition = {
   read: ReadResourceTemplateCallback;
 };
 
+// Optional function to assist with formatting resource results
 export async function formatResult(
   value: unknown,
   uri: URL,

package/src/mcp-server/server.ts

@@ -6,6 +6,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { S2Core } from "../core.js";
 import { SDKOptions } from "../lib/config.js";
 import type { ConsoleLogger } from "./console-logger.js";
+import { createRegisterPrompt } from "./prompts.js";
 import {
   createRegisterResource,
   createRegisterResourceTemplate,
@@ -36,7 +37,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "S2",
-    version: "0.8.2",
+    version: "0.9.0",
   });
 
   const client = new S2Core({
@@ -62,7 +63,8 @@ export function createMCPServer(deps: {
     client,
     scopes,
   );
-  const register = { tool, resource, resourceTemplate };
+  const prompt = createRegisterPrompt(deps.logger, server, client, scopes);
+  const register = { tool, resource, resourceTemplate, prompt };
   void register; // suppress unused warnings
 
   tool(tool$accountListBasins);

package/src/mcp-server/tools.ts

@@ -34,6 +34,7 @@ export type ToolDefinition<Args extends undefined | ZodRawShape = undefined> =
       ) => CallToolResult | Promise<CallToolResult>;
     };
 
+// Optional function to assist with formatting tool results
 export async function formatResult(
   value: unknown,
   init: { response?: Response | undefined },

package/src/models/components/appendrecord.ts

@@ -19,6 +19,15 @@ export type AppendRecord = {
    * Series of name-value pairs for this record.
    */
   headers?: Array<Array<string>> | undefined;
+  /**
+   * Timestamp for this record in milliseconds since Unix epoch.
+   *
+   * @remarks
+   * The service ensures monotonicity by adjusting it up if necessary to the maximum observed timestamp.
+   * A timestamp detected to be in the future will be adjusted down.
+   * If not provided, the semantics depend on the stream's `require_client_timestamps` config.
+   */
+  timestamp?: number | null | undefined;
 };
 
 /** @internal */
@@ -29,12 +38,14 @@ export const AppendRecord$inboundSchema: z.ZodType<
 > = z.object({
   body: z.string(),
   headers: z.array(z.array(z.string())).optional(),
+  timestamp: z.nullable(z.number().int()).optional(),
 });
 
 /** @internal */
 export type AppendRecord$Outbound = {
   body: string;
   headers?: Array<Array<string>> | undefined;
+  timestamp?: number | null | undefined;
 };
 
 /** @internal */
@@ -45,6 +56,7 @@ export const AppendRecord$outboundSchema: z.ZodType<
 > = z.object({
   body: z.string(),
   headers: z.array(z.array(z.string())).optional(),
+  timestamp: z.nullable(z.number().int()).optional(),
 });
 
 /**

package/src/models/components/output.ts

@@ -15,35 +15,37 @@ import {
 } from "./sequencedrecordbatch.js";
 
 /**
- * Sequence number for the next record on this stream, in case the requested `start_seq_num` was larger.
+ * Sequence number that will be assigned to the next record on this stream.
  *
  * @remarks
- * If returned in a streaming read session, this will be a terminal reply.
+ * This will be returned either because the requested `start_seq_num` was larger,
+ * or in case of a limited read, equal to it.
  */
 export type NextSeqNum = {
   /**
-   * Sequence number for the next record on this stream, in case the requested `start_seq_num` was larger.
+   * Sequence number that will be assigned to the next record on this stream.
    *
    * @remarks
-   * If returned in a streaming read session, this will be a terminal reply.
+   * This will be returned either because the requested `start_seq_num` was larger,
+   * or in case of a limited read, equal to it.
    */
   nextSeqNum: number;
 };
 
 /**
- * Sequence number for the first record on this stream, in case the requested `start_seq_num` is smaller.
+ * Sequence number for the first record on this stream.
  *
  * @remarks
- * If returned in a streaming read session, this will be a terminal reply, to signal that there is uncertainty about whether some records may be omitted.
- * The client can re-establish the session starting at this sequence number.
+ * Typically this will be returned when the requested `start_seq_num` was smaller.
+ * It may also be returned during a session, if the stream gets concurrently trimmed.
  */
 export type FirstSeqNum = {
   /**
-   * Sequence number for the first record on this stream, in case the requested `start_seq_num` is smaller.
+   * Sequence number for the first record on this stream.
    *
    * @remarks
-   * If returned in a streaming read session, this will be a terminal reply, to signal that there is uncertainty about whether some records may be omitted.
-   * The client can re-establish the session starting at this sequence number.
+   * Typically this will be returned when the requested `start_seq_num` was smaller.
+   * It may also be returned during a session, if the stream gets concurrently trimmed.
    */
   firstSeqNum: number;
 };
@@ -52,8 +54,8 @@ export type FirstSeqNum = {
  * Batch of records.
  *
  * @remarks
- * This batch can be empty only if a `ReadLimit` was provided in the associated read request, but the first record
- * that could have been returned would violate the limit.
+ * It can only be empty when not in a session context (which implies a limit),
+ * if the first record that could have been retrieved would violate the limit.
  */
 export type Batch = {
   /**
@@ -63,7 +65,10 @@ export type Batch = {
 };
 
 /**
- * Reply which can be a batch of records, or a sequence number if the request could not be satisfied.
+ * Batch of records, or a sequence number if the read could not be satisfied.
+ *
+ * @remarks
+ * An empty batch or a sequence number output will be a terminal message in a session.
  */
 export type Output = Batch | FirstSeqNum | NextSeqNum;
 

package/src/models/components/readresponse.ts

@@ -41,7 +41,10 @@ export type Event = ClosedEnum<typeof Event>;
 
 export type Message = {
   /**
-   * Reply which can be a batch of records, or a sequence number if the request could not be satisfied.
+   * Batch of records, or a sequence number if the read could not be satisfied.
+   *
+   * @remarks
+   * An empty batch or a sequence number output will be a terminal message in a session.
    */
   data: Output;
   event: Event;

package/src/models/components/sequencedrecord.ts

@@ -27,9 +27,13 @@ export type SequencedRecord = {
    */
   headers: Array<Header>;
   /**
-   * Sequence number for this record.
+   * Sequence number assigned to this record.
    */
   seqNum: number;
+  /**
+   * Timestamp for this record in milliseconds since Unix epoch.
+   */
+  timestamp: number;
 };
 
 /** @internal */
@@ -41,6 +45,7 @@ export const SequencedRecord$inboundSchema: z.ZodType<
   body: z.string(),
   headers: z.array(Header$inboundSchema),
   seq_num: z.number().int(),
+  timestamp: z.number().int(),
 }).transform((v) => {
   return remap$(v, {
     "seq_num": "seqNum",
@@ -52,6 +57,7 @@ export type SequencedRecord$Outbound = {
   body: string;
   headers: Array<Header$Outbound>;
   seq_num: number;
+  timestamp: number;
 };
 
 /** @internal */
@@ -63,6 +69,7 @@ export const SequencedRecord$outboundSchema: z.ZodType<
   body: z.string(),
   headers: z.array(Header$outboundSchema),
   seqNum: z.number().int(),
+  timestamp: z.number().int(),
 }).transform((v) => {
   return remap$(v, {
     seqNum: "seq_num",

package/src/models/components/streamconfig.ts

@@ -23,6 +23,14 @@ import {
  * Stream configuration.
  */
 export type StreamConfig = {
+  /**
+   * Controls how to handle timestamps when they are not provided by the client.
+   *
+   * @remarks
+   * If this is false (or not set), the record's arrival time will be assigned as its timestamp.
+   * If this is true, then any append without a client-specified timestamp will be rejected as invalid.
+   */
+  requireClientTimestamps?: boolean | null | undefined;
   retentionPolicy?: RetentionPolicy | null | undefined;
   /**
    * Storage class for recent writes.
@@ -36,10 +44,12 @@ export const StreamConfig$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
+  require_client_timestamps: z.nullable(z.boolean()).optional(),
   retention_policy: z.nullable(RetentionPolicy$inboundSchema).optional(),
   storage_class: StorageClass$inboundSchema.optional(),
 }).transform((v) => {
   return remap$(v, {
+    "require_client_timestamps": "requireClientTimestamps",
     "retention_policy": "retentionPolicy",
     "storage_class": "storageClass",
   });
@@ -47,6 +57,7 @@ export const StreamConfig$inboundSchema: z.ZodType<
 
 /** @internal */
 export type StreamConfig$Outbound = {
+  require_client_timestamps?: boolean | null | undefined;
   retention_policy?: RetentionPolicy$Outbound | null | undefined;
   storage_class?: string | undefined;
 };
@@ -57,10 +68,12 @@ export const StreamConfig$outboundSchema: z.ZodType<
   z.ZodTypeDef,
   StreamConfig
 > = z.object({
+  requireClientTimestamps: z.nullable(z.boolean()).optional(),
   retentionPolicy: z.nullable(RetentionPolicy$outboundSchema).optional(),
   storageClass: StorageClass$outboundSchema.optional(),
 }).transform((v) => {
   return remap$(v, {
+    requireClientTimestamps: "require_client_timestamps",
     retentionPolicy: "retention_policy",
     storageClass: "storage_class",
   });

package/src/models/operations/read.ts

@@ -18,7 +18,11 @@ export const ReadServerList = [
 ] as const;
 
 /**
- * Limit on how many records can be returned upto a maximum of 1000, or 1MiB of metered bytes.
+ * Limit how many records can be returned.
+ *
+ * @remarks
+ * This will get capped at the default limit,
+ * which is up to 1000 records or 1MiB of metered bytes.
  */
 export type Limit = {
   /**
@@ -45,7 +49,11 @@ export type ReadRequest = {
    */
   startSeqNum?: number | undefined;
   /**
-   * Limit on how many records can be returned upto a maximum of 1000, or 1MiB of metered bytes.
+   * Limit how many records can be returned.
+   *
+   * @remarks
+   * This will get capped at the default limit,
+   * which is up to 1000 records or 1MiB of metered bytes.
    */
   limit?: Limit | undefined;
   /**