@s2-dev/streamstore 0.11.2 → 0.13.1

package/README.md

@@ -22,12 +22,12 @@ S2 API: Serverless API for streaming data backed by object storage.
 <!-- $toc-max-depth=2 -->
 * [streamstore](#streamstore)
   * [SDK Installation](#sdk-installation)
-  * [Requirements](#requirements)
-  * [SDK Recommended Usage](#sdk-recommended-usage)
+  * [Requirements](#requirements)  
   * [SDK Example Usage](#sdk-example-usage)
   * [Authentication](#authentication)
   * [Available Resources and Operations](#available-resources-and-operations)
   * [Standalone functions](#standalone-functions)
+  * [Server-sent event streaming](#server-sent-event-streaming)
   * [Pagination](#pagination)
   * [Retries](#retries)
   * [Error Handling](#error-handling)
@@ -166,85 +166,6 @@ npx -y --package @s2-dev/streamstore -- mcp start --help
 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({ authToken: "<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();
-```
-### Examples
-
-- Using `S2Endpoints`
-
-```typescript
-const endpoints = new S2Endpoints(
-  "aws.s2.dev",
-  {
-      kind: BasinEndpointKind.Direct,
-      authority: "aws.s2.dev"
-  }
-);
-
-const s2 = new S2Client({ authToken: "<AUTH_TOKEN>", endpoints });
-async function run() {
-  const allStreams = await s2.account.basin("my-favorite-basin").listStreams();
-  for await (const stream of allStreams) {
-    console.log(basin);
-  }
-}
-
-run();
-```
-
-- Override Client level Auth token
-
-```typescript
-const s2 = new S2Client({ authToken: "<AUTH_TOKEN>"});
-async function run() {
-  const refreshedToken = await fetchToken();
-  await s2.account.deleteBasin("my-favorite-basin", { authToken: refreshedToken });
-}
-
-run();
-```
-
-- Set custom user-agent
-
-```typescript
-const s2 = new S2Client({ authToken: "<AUTH_TOKEN>", userAgent: "say-cheese" });
-async function run() {
-  const config = await s2.account.getBasinConfig("mehul-test");
-  console.log(config);
-}
-
-run();
-```
-
-- List Basins
-
-```typescript
-  const s2 = new S2Client({ authToken: "<AUTH_TOKEN>" });
-  async function run() {
-    const allBasins = await s2.account.listBasins();
-    for await (const basin of allBasins) {
-      console.log(basin);
-    }
-  }
-
-  run();
-```
-
 <!-- Start SDK Example Usage [usage] -->
 ## SDK Example Usage
 
@@ -315,6 +236,7 @@ run();
 ### [basins](docs/sdks/basins/README.md)
 
 * [listBasins](docs/sdks/basins/README.md#listbasins) - List basins.
+* [createBasin](docs/sdks/basins/README.md#createbasin) - Create a basin.
 * [getBasinConfig](docs/sdks/basins/README.md#getbasinconfig) - Get basin config.
 * [createOrReconfigureBasin](docs/sdks/basins/README.md#createorreconfigurebasin) - Create or reconfigure a basin.
 * [deleteBasin](docs/sdks/basins/README.md#deletebasin) - Delete a basin.
@@ -322,12 +244,15 @@ run();
 
 ### [records](docs/sdks/records/README.md)
 
+* [read](docs/sdks/records/README.md#read) - Retrieve records.
+* [append](docs/sdks/records/README.md#append) - Append records.
 * [checkTail](docs/sdks/records/README.md#checktail) - Check the tail.
 
 
 ### [streams](docs/sdks/streams/README.md)
 
 * [listStreams](docs/sdks/streams/README.md#liststreams) - List streams.
+* [createStream](docs/sdks/streams/README.md#createstream) - Create a stream.
 * [getStreamConfig](docs/sdks/streams/README.md#getstreamconfig) - Get stream configuration.
 * [createOrReconfigureStream](docs/sdks/streams/README.md#createorreconfigurestream) - Create or reconfigure a stream.
 * [deleteStream](docs/sdks/streams/README.md#deletestream) - Delete a stream.
@@ -354,13 +279,17 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`accessTokensIssueAccessToken`](docs/sdks/accesstokens/README.md#issueaccesstoken) - Issue a new access token.
 - [`accessTokensListAccessTokens`](docs/sdks/accesstokens/README.md#listaccesstokens) - List access tokens.
 - [`accessTokensRevokeAccessToken`](docs/sdks/accesstokens/README.md#revokeaccesstoken) - Revoke an access token.
+- [`basinsCreateBasin`](docs/sdks/basins/README.md#createbasin) - Create a basin.
 - [`basinsCreateOrReconfigureBasin`](docs/sdks/basins/README.md#createorreconfigurebasin) - Create or reconfigure a basin.
 - [`basinsDeleteBasin`](docs/sdks/basins/README.md#deletebasin) - Delete a basin.
 - [`basinsGetBasinConfig`](docs/sdks/basins/README.md#getbasinconfig) - Get basin config.
 - [`basinsListBasins`](docs/sdks/basins/README.md#listbasins) - List basins.
 - [`basinsReconfigureBasin`](docs/sdks/basins/README.md#reconfigurebasin) - Reconfigure a basin.
+- [`recordsAppend`](docs/sdks/records/README.md#append) - Append records.
 - [`recordsCheckTail`](docs/sdks/records/README.md#checktail) - Check the tail.
+- [`recordsRead`](docs/sdks/records/README.md#read) - Retrieve records.
 - [`streamsCreateOrReconfigureStream`](docs/sdks/streams/README.md#createorreconfigurestream) - Create or reconfigure a stream.
+- [`streamsCreateStream`](docs/sdks/streams/README.md#createstream) - Create a stream.
 - [`streamsDeleteStream`](docs/sdks/streams/README.md#deletestream) - Delete a stream.
 - [`streamsGetStreamConfig`](docs/sdks/streams/README.md#getstreamconfig) - Get stream configuration.
 - [`streamsListStreams`](docs/sdks/streams/README.md#liststreams) - List streams.
@@ -369,6 +298,42 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 </details>
 <!-- End Standalone functions [standalone-funcs] -->
 
+<!-- Start Server-sent event streaming [eventstream] -->
+## Server-sent event streaming
+
+[Server-sent events][mdn-sse] are used to stream content from certain
+operations. These operations will expose the stream as an async iterable that
+can be consumed using a [`for await...of`][mdn-for-await-of] loop. The loop will
+terminate when the server no longer has any events to send and closes the
+underlying connection.
+
+```typescript
+import { S2 } from "@s2-dev/streamstore";
+
+const s2 = new S2({
+  accessToken: process.env["S2_ACCESS_TOKEN"] ?? "",
+});
+
+async function run() {
+  const result = await s2.records.read({
+    stream: "<value>",
+    s2Basin: "<value>",
+  });
+
+  for await (const event of result) {
+    // Handle the event
+    console.log(event);
+  }
+}
+
+run();
+
+```
+
+[mdn-sse]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
+[mdn-for-await-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
+<!-- End Server-sent event streaming [eventstream] -->
+
 <!-- Start Pagination [pagination] -->
 ## Pagination
 
@@ -472,12 +437,10 @@ run();
 
 Some methods specify known errors which can be thrown. All the known errors are enumerated in the `models/errors/errors.ts` module. The known errors for a method are documented under the *Errors* tables in SDK docs. For example, the `listAccessTokens` method may throw the following errors:
 
-| Error Type            | Status Code   | Content Type     |
-| --------------------- | ------------- | ---------------- |
-| errors.ErrorResponse  | 400, 401      | application/json |
-| errors.RetryableError | 499           | application/json |
-| errors.RetryableError | 500, 503, 504 | application/json |
-| errors.APIError       | 4XX, 5XX      | \*/\*            |
+| Error Type           | Status Code | Content Type     |
+| -------------------- | ----------- | ---------------- |
+| errors.ErrorResponse | 400, 403    | application/json |
+| errors.APIError      | 4XX, 5XX    | \*/\*            |
 
 If the method throws an error and it is not captured by the known errors, it will default to throwing a `APIError`.
 
@@ -485,7 +448,6 @@ If the method throws an error and it is not captured by the known errors, it wil
 import { S2 } from "@s2-dev/streamstore";
 import {
   ErrorResponse,
-  RetryableError,
   SDKValidationError,
 } from "@s2-dev/streamstore/models/errors";
 
@@ -515,16 +477,6 @@ async function run() {
         console.error(err);
         return;
       }
-      case (err instanceof RetryableError): {
-        // Handle err.data$: RetryableErrorData
-        console.error(err);
-        return;
-      }
-      case (err instanceof RetryableError): {
-        // Handle err.data$: RetryableErrorData
-        console.error(err);
-        return;
-      }
       default: {
         // Other errors such as network errors, see HTTPClientErrors for more details
         throw err;
@@ -586,7 +538,9 @@ const s2 = new S2({
 });
 
 async function run() {
-  const result = await s2.streams.listStreams({}, {
+  const result = await s2.streams.listStreams({
+    s2Basin: "<value>",
+  }, {
     serverURL: "https://.b.aws.s2.dev/v1",
   });