chore: docs + methods

Author: infiniteregrets

.speakeasy/gen.lock

@@ -3,18 +3,18 @@ id: 2d20490e-9921-47d5-9711-d3c4b91c8cfa
 management:
   docChecksum: bbcb28d2548a56b38ad64847eb7a88d2
   docVersion: 1.0.0
-  speakeasyVersion: 1.484.1
-  generationVersion: 2.503.2
-  releaseVersion: 0.2.17
-  configChecksum: 220a5abcbf94f9e343d247580db0d79b
+  speakeasyVersion: 1.486.0
+  generationVersion: 2.505.0
+  releaseVersion: 0.3.1
+  configChecksum: 4a66bdf60a97497ae0e2e3985a19a6ea
   repoURL: https://github.com/s2-streamstore/s2-sdk-typescript.git
   installationURL: https://github.com/s2-streamstore/s2-sdk-typescript
   published: true
 features:
   typescript:
     acceptHeaders: 2.81.2
     additionalDependencies: 0.1.0
-    core: 3.18.22
+    core: 3.19.0
     defaultEnabledRetries: 0.1.0
     devContainers: 2.90.0
     enumUnions: 0.1.0

.speakeasy/gen.yaml

@@ -16,7 +16,7 @@ generation:
     oAuth2ClientCredentialsEnabled: true
     oAuth2PasswordEnabled: true
 typescript:
-  version: 0.2.17
+  version: 0.3.1
   additionalDependencies:
     dependencies:
       uuid: ^9.0.1

.speakeasy/workflow.lock

@@ -1,8 +1,8 @@
-speakeasyVersion: 1.484.1
+speakeasyVersion: 1.486.0
 sources:
     S2 API:
         sourceNamespace: s-2-api
-        sourceRevisionDigest: sha256:448a206cc01c74de7c0ca8c59c935b356b29e320715d548978d02cfafd9feed4
+        sourceRevisionDigest: sha256:d4fc6ea07af52c1783bb9171e22c9abf7de0909abda18316ebd42f4809e31ef2
         sourceBlobDigest: sha256:eda67f586b78ceb1300a3662669e008175f0667b68ff804d4de23fcab20998d1
         tags:
             - latest
@@ -11,10 +11,10 @@ targets:
     streamstore:
         source: S2 API
         sourceNamespace: s-2-api
-        sourceRevisionDigest: sha256:448a206cc01c74de7c0ca8c59c935b356b29e320715d548978d02cfafd9feed4
+        sourceRevisionDigest: sha256:d4fc6ea07af52c1783bb9171e22c9abf7de0909abda18316ebd42f4809e31ef2
         sourceBlobDigest: sha256:eda67f586b78ceb1300a3662669e008175f0667b68ff804d4de23fcab20998d1
         codeSamplesNamespace: s-2-api-typescript-code-samples
-        codeSamplesRevisionDigest: sha256:5615d0689deba52dd5e6ae379589ebd086858029d7a36e133089763f73d61ddc
+        codeSamplesRevisionDigest: sha256:0122b1b27af865f5ca17e1900a90a3f2cbff5047995ee8ce729f3ce03a58b9b8
 workflow:
     workflowVersion: 1.0.0
     speakeasyVersion: latest

README.md

@@ -23,6 +23,7 @@ S2 API: Serverless API for streaming data backed by object storage.
 * [streamstore](#streamstore)
   * [SDK Installation](#sdk-installation)
   * [Requirements](#requirements)
+  * [SDK Recommended Usage](#sdk-recommended-usage)
   * [SDK Example Usage](#sdk-example-usage)
   * [Authentication](#authentication)
   * [Available Resources and Operations](#available-resources-and-operations)
@@ -79,6 +80,24 @@ yarn add @s2-dev/streamstore zod
 For supported JavaScript runtimes, please consult [RUNTIMES.md](RUNTIMES.md).
 <!-- End Requirements [requirements] -->
 
+## SDK Recommended Usage
+
+The `S2Client` class provides a lot of convenience over the generated methods and is the recommended way to interact with the SDK. If you need finer control over the internal functions, you may use [Generated functions](#available-resources-and-operations)
+ or [Standalone functions](#standalone-functions).
+
+```typescript
+import { ReadRequest, S2Client } from "@s2-dev/streamstore";
+
+const s2 = new S2Client("<AUTH_TOKEN>");
+
+async function run() {
+  await s2.account.createBasin("my-favorite-basin");  
+  await s2.account.basin("my-favorite-basin").stream("test").append({ appendInput: { records: [{ body: "hello" }] } });  
+}
+
+run();
+```
+
 <!-- Start SDK Example Usage [usage] -->
 ## SDK Example Usage
 

jsr.json

@@ -2,7 +2,7 @@
 
 {
   "name": "@s2-dev/streamstore",
-  "version": "0.2.17",
+  "version": "0.3.1",
   "exports": {
     ".": "./src/index.ts",    
     "./models/errors": "./src/models/errors/index.ts",    

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2-dev/streamstore",
-  "version": "0.2.17",
+  "version": "0.3.1",
   "author": "Speakeasy",
   "main": "./index.js",
   "sideEffects": false,

package.json

@@ -1,25 +1,40 @@
 import { accountDeleteBasin } from "./funcs/accountDeleteBasin";
 import { RequestOptions } from "./lib/sdks";
-import { BasinConfig, BasinInfo, CheckTailResponse, CreateBasinRequest, CreateStreamRequest, StreamConfig, StreamInfo } from "./models/components";
+import { AppendOutput, BasinConfig, BasinInfo, CheckTailResponse, CreateBasinRequest, CreateStreamRequest, Output, ReadResponse, StreamConfig, StreamInfo } from "./models/components";
 import { NotFoundError } from "./models/errors";
-import {    
+import {
     GetBasinConfigRequest,
     ListBasinsRequest,
     ListBasinsResponse,
     ListStreamsRequest,
     ListStreamsResponse,
     ReconfigureBasinRequest,
     CreateBasinRequest as CreateBasinRequestInner,
-    CreateStreamRequest as CreateStreamRequestInner
+    CreateStreamRequest as CreateStreamRequestInner,
+    ReadRequest as ReadRequestInner,
+    AppendRequest as AppendRequestInner,
 } from "./models/operations";
 import { PageIterator } from "./types";
 
-import { Stream as InnerStream } from "./sdk/stream";
+import { Stream as InnerStream, ReadAcceptEnum } from "./sdk/stream";
 import { Basin as InnerBasin } from "./sdk/basin";
 import { Account as InnerAccount } from "./sdk/account";
 
 import { v4 } from 'uuid';
 import { basinDeleteStream } from "./funcs/basinDeleteStream";
+import { EventStream } from "./lib/event-streams";
+
+export type ReadRequest = Omit<ReadRequestInner, 'stream'>;
+export type AppendRequest = Omit<AppendRequestInner, 'stream'>;
+export type {
+    GetBasinConfigRequest,
+    ListBasinsRequest,
+    ListBasinsResponse,
+    ListStreamsRequest,
+    ListStreamsResponse,
+    ReconfigureBasinRequest,
+} from "./models/operations";
+export type { BasinConfig, BasinInfo, CheckTailResponse, CreateBasinRequest, CreateStreamRequest, Output, ReadResponse, StreamConfig, StreamInfo } from "./models/components";
 
 export function genS2RequestToken(): string {
     return v4().replace(/-/g, '');
@@ -45,9 +60,11 @@ export class S2Client {
 class S2Account {
     private _account: InnerAccount;
     private requestOptions: RequestOptions;
+    private authToken: string;
 
     constructor(authToken: string) {
         this._account = new InnerAccount({ bearerAuth: authToken });
+        this.authToken = authToken;
         this.requestOptions = {
             timeoutMs: 3000,
             retries: {
@@ -64,9 +81,10 @@ class S2Account {
         };
     }
 
-    /**
-    * List basins.
-    */
+    basin(basinName: string): S2Basin {
+        return new S2Basin(this.authToken, basinName);
+    }
+
     async listBasins(
         request?: ListBasinsRequest,
     ): Promise<PageIterator<ListBasinsResponse, { cursor: string }>> {
@@ -132,7 +150,7 @@ class S2Basin {
     }
 
     stream(streamName: string): Stream {
-        return (this._stream ??= new Stream(streamName, this.basinName));
+        return (this._stream ??= new Stream(this.basinName, streamName));
     }
 
     async listStreams(
@@ -151,13 +169,13 @@ class S2Basin {
 
     async createStream(
         stream: string,
-        request: CreateStreamRequest,
+        request?: CreateStreamRequest,
     ): Promise<StreamInfo | undefined> {
         const basinURL = `${this.basinName}.${this.basinURLSuffx}`;
         const _request: CreateStreamRequestInner = {
             stream,
             s2RequestToken: genS2RequestToken(),
-            createStreamRequest: request,
+            createStreamRequest: request ?? {},
         };
 
         return (
@@ -170,7 +188,7 @@ class S2Basin {
         const response = await basinDeleteStream(this._basin, { stream }, { serverURL: basinURL, ...this.requestOptions });
         if (if_exists && response instanceof NotFoundError) return;
         if (response.error) throw new Error(response.error.message);
-        return;        
+        return;
     }
 
     async reconfigureStream(stream: string, config: StreamConfig): Promise<StreamConfig | undefined> {
@@ -184,15 +202,16 @@ class S2Basin {
     }
 }
 
+
 class Stream {
     private _stream: InnerStream;
-    private streamName: string;
     private basinName: string;
+    private streamName: string;
     private readonly basinURLSuffx = 'b.aws.s2.dev/v1alpha';
 
-    constructor(streamName: string, basinName: string) {
-        this.streamName = streamName;
+    constructor(basinName: string, streamName: string) {
         this.basinName = basinName;
+        this.streamName = streamName;
         this._stream = new InnerStream();
     }
 
@@ -201,4 +220,28 @@ class Stream {
         return (await this._stream.checkTail({ stream: this.streamName }, { serverURL: basinURL }))
             .checkTailResponse;
     }
+
+    async read(
+        request: ReadRequest,
+        stream?: boolean
+    ): Promise<EventStream<ReadResponse> | Output | undefined> {
+        const basinURL = `${this.basinName}.${this.basinURLSuffx}`;
+        return (await this._stream.read(
+            { ...request, stream: this.streamName },
+            stream
+                ? { serverURL: basinURL, acceptHeaderOverride: ReadAcceptEnum.textEventStream }
+                : { serverURL: basinURL }
+        ))
+            .readResponse;
+    }
+
+    async append(
+        request: AppendRequest,        
+    ): Promise<AppendOutput | undefined> {
+        const basinURL = `${this.basinName}.${this.basinURLSuffx}`;
+        return (await this._stream.append(
+            { ...request, stream: this.streamName },
+            { serverURL: basinURL }
+        )).appendOutput;
+    }
 }

src/index.extras.ts

@@ -54,8 +54,7 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "1.0.0",
-  sdkVersion: "0.2.17",
-  genVersion: "2.503.2",
-  userAgent:
-    "speakeasy-sdk/typescript 0.2.17 2.503.2 1.0.0 @s2-dev/streamstore",
+  sdkVersion: "0.3.1",
+  genVersion: "2.505.0",
+  userAgent: "speakeasy-sdk/typescript 0.3.1 2.505.0 1.0.0 @s2-dev/streamstore",
 } as const;