@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/kinesis/README.md

@@ -1,153 +0,0 @@
-# Kinesis Client
-
-Write records to and read records from Amazon Kinesis Data Streams.
-
-## Methods
-
-| Method                          | Description                               |
-| ------------------------------- | ----------------------------------------- |
-| `putRecord(params, metadata?)`  | Write a single record to a Kinesis stream |
-| `getRecords(params, metadata?)` | Read records from a Kinesis stream shard  |
-
-## Usage
-
-### Put Record
-
-```typescript
-import { api, z, kinesis } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_KINESIS = "a1b2c3d4-5678-90ab-cdef-kinesis00001";
-
-export default api({
-  integrations: {
-    kinesis: kinesis(PROD_KINESIS),
-  },
-  name: "KinesisExample",
-  input: z.object({
-    userId: z.string(),
-    event: z.string(),
-  }),
-  output: z.object({
-    success: z.boolean(),
-  }),
-  async run(ctx, { userId, event }) {
-    await kinesis.putRecord({
-      data: JSON.stringify({ event, userId, timestamp: Date.now() }),
-      partitionKey: userId,
-      streamName: "user-events",
-    });
-
-    return { success: true };
-  },
-});
-```
-
-### Put Record with Stream ARN
-
-```typescript
-await kinesis.putRecord({
-  data: JSON.stringify({ event: "signup" }),
-  partitionKey: "user-123",
-  streamIdentifierType: "STREAM_ARN",
-  streamArn: "arn:aws:kinesis:us-east-1:123456789:stream/user-events",
-});
-```
-
-### Get Records
-
-```typescript
-const records = await kinesis.getRecords({
-  shardId: "shardId-000000000000",
-  shardIteratorType: "LATEST",
-  streamName: "user-events",
-  limit: 10,
-});
-```
-
-### Get Records from Specific Sequence Number
-
-```typescript
-const records = await kinesis.getRecords({
-  shardId: "shardId-000000000000",
-  shardIteratorType: "AFTER_SEQUENCE_NUMBER",
-  startingSequenceNumber:
-    "49590338271490256608559692538361571095921575989136588898",
-  streamName: "user-events",
-});
-```
-
-### Get Records at Timestamp
-
-```typescript
-const records = await kinesis.getRecords({
-  shardId: "shardId-000000000000",
-  shardIteratorType: "AT_TIMESTAMP",
-  timestamp: "2024-01-15T00:00:00Z",
-  streamName: "user-events",
-});
-```
-
-## Parameters
-
-### KinesisPutParams
-
-| Parameter              | Type                            | Required | Description                                  |
-| ---------------------- | ------------------------------- | -------- | -------------------------------------------- |
-| `data`                 | `string`                        | Yes      | The data payload (JSON string or raw string) |
-| `partitionKey`         | `string`                        | Yes      | The partition key for the record             |
-| `streamIdentifierType` | `'STREAM_NAME' \| 'STREAM_ARN'` | No       | How to identify the stream                   |
-| `streamName`           | `string`                        | No       | Stream name (when using STREAM_NAME)         |
-| `streamArn`            | `string`                        | No       | Stream ARN (when using STREAM_ARN)           |
-
-### KinesisGetParams
-
-| Parameter                | Type                            | Required | Description                                    |
-| ------------------------ | ------------------------------- | -------- | ---------------------------------------------- |
-| `shardId`                | `string`                        | Yes      | The shard ID to read from                      |
-| `shardIteratorType`      | `ShardIteratorType`             | Yes      | How to position the shard iterator             |
-| `limit`                  | `number`                        | No       | Maximum number of records to return            |
-| `pollingCooldownMs`      | `number`                        | No       | Polling cooldown in milliseconds               |
-| `startingSequenceNumber` | `string`                        | No       | Sequence number (for AT/AFTER_SEQUENCE_NUMBER) |
-| `timestamp`              | `string`                        | No       | ISO timestamp (for AT_TIMESTAMP)               |
-| `streamIdentifierType`   | `'STREAM_NAME' \| 'STREAM_ARN'` | No       | How to identify the stream                     |
-| `streamName`             | `string`                        | No       | Stream name (when using STREAM_NAME)           |
-| `streamArn`              | `string`                        | No       | Stream ARN (when using STREAM_ARN)             |
-
-### Shard Iterator Types
-
-| Type                    | Description                               |
-| ----------------------- | ----------------------------------------- |
-| `AT_SEQUENCE_NUMBER`    | Start at the specified sequence number    |
-| `AFTER_SEQUENCE_NUMBER` | Start after the specified sequence number |
-| `AT_TIMESTAMP`          | Start at the specified timestamp          |
-| `TRIM_HORIZON`          | Start at the oldest record in the shard   |
-| `LATEST`                | Start at the most recent record           |
-
-## Trace Metadata
-
-All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
-
-## Error Handling
-
-```typescript
-import { IntegrationError } from "@superblocksteam/sdk-api";
-
-try {
-  await kinesis.putRecord({
-    data: JSON.stringify({ event: "test" }),
-    partitionKey: "key-1",
-    streamName: "my-stream",
-  });
-} catch (error) {
-  if (error instanceof IntegrationError) {
-    console.error("Kinesis error:", error.message);
-  }
-}
-```
-
-## API Reference
-
-- [Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/introduction.html)
-- [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)
-- [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html)

package/src/integrations/kinesis/client.ts

@@ -1,146 +0,0 @@
-/**
- * Kinesis client implementation.
- *
- * Uses the native Kinesis plugin type from @superblocksteam/types.
- * Supports PUT (write records) and GET (read records) operations.
- */
-
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
-import { IntegrationError } from "../../runtime/errors.js";
-import type {
-  KinesisClient,
-  KinesisPutParams,
-  KinesisGetParams,
-} from "./types.js";
-
-/**
- * Kinesis operation type enum values matching the proto.
- */
-const OPERATION_TYPE = {
-  PUT: "OPERATION_TYPE_PUT",
-  GET: "OPERATION_TYPE_GET",
-} as const;
-
-/**
- * Internal implementation of KinesisClient.
- *
- * Sends requests matching the Kinesis plugin proto structure:
- * - `operationType`: PUT or GET
- * - `put`: PUT operation parameters
- * - `get`: GET operation parameters
- */
-export class KinesisClientImpl implements KinesisClient, IntegrationClientImpl {
-  readonly config: IntegrationConfig;
-  private readonly executeQuery: QueryExecutor;
-
-  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
-    this.config = config;
-    this.executeQuery = executeQuery;
-  }
-
-  get name(): string {
-    return this.config.name;
-  }
-
-  get pluginId(): string {
-    return this.config.pluginId;
-  }
-
-  /**
-   * Execute a request and wrap errors.
-   */
-  private async exec(
-    request: Record<string, unknown>,
-    operation: string,
-    metadata?: TraceMetadata,
-  ): Promise<unknown> {
-    try {
-      return await this.executeQuery(request, undefined, metadata);
-    } catch (error) {
-      if (error instanceof IntegrationError) {
-        throw error;
-      }
-
-      throw new IntegrationError(this.config.name, operation, error);
-    }
-  }
-
-  async putRecord(
-    params: KinesisPutParams,
-    metadata?: TraceMetadata,
-  ): Promise<unknown> {
-    const put: Record<string, unknown> = {
-      data: params.data,
-      partitionKey: params.partitionKey,
-    };
-
-    if (params.streamIdentifierType) {
-      put.streamIdentifierType = params.streamIdentifierType;
-    }
-
-    if (params.streamName) {
-      put.streamName = params.streamName;
-    }
-
-    if (params.streamArn) {
-      put.streamArn = params.streamArn;
-    }
-
-    return this.exec(
-      {
-        operationType: OPERATION_TYPE.PUT,
-        put,
-      },
-      "putRecord",
-      metadata,
-    );
-  }
-
-  async getRecords(
-    params: KinesisGetParams,
-    metadata?: TraceMetadata,
-  ): Promise<unknown> {
-    const get: Record<string, unknown> = {
-      shardId: params.shardId,
-      shardIteratorType: params.shardIteratorType,
-    };
-
-    if (params.limit !== undefined) {
-      get.limit = params.limit;
-    }
-
-    if (params.pollingCooldownMs !== undefined) {
-      get.pollingCooldownMs = params.pollingCooldownMs;
-    }
-
-    if (params.startingSequenceNumber) {
-      get.startingSequenceNumber = params.startingSequenceNumber;
-    }
-
-    if (params.timestamp) {
-      get.timestamp = params.timestamp;
-    }
-
-    if (params.streamIdentifierType) {
-      get.streamIdentifierType = params.streamIdentifierType;
-    }
-
-    if (params.streamName) {
-      get.streamName = params.streamName;
-    }
-
-    if (params.streamArn) {
-      get.streamArn = params.streamArn;
-    }
-
-    return this.exec(
-      {
-        operationType: OPERATION_TYPE.GET,
-        get,
-      },
-      "getRecords",
-      metadata,
-    );
-  }
-}

package/src/integrations/kinesis/index.ts

@@ -1,14 +0,0 @@
-/**
- * Kinesis integration client.
- *
- * @module
- */
-
-export type {
-  KinesisClient,
-  KinesisPutParams,
-  KinesisGetParams,
-  KinesisStreamIdentifier,
-  KinesisShardIteratorType,
-} from "./types.js";
-export { KinesisClientImpl } from "./client.js";

package/src/integrations/kinesis/types.ts

@@ -1,114 +0,0 @@
-/**
- * Kinesis client types.
- *
- * Kinesis uses a dedicated plugin (not REST API) with PUT and GET operations.
- */
-
-import type { BaseIntegrationClient } from "../../types.js";
-import type { TraceMetadata } from "../registry.js";
-
-/**
- * Stream identifier type for Kinesis operations.
- */
-export type KinesisStreamIdentifier = "STREAM_NAME" | "STREAM_ARN";
-
-/**
- * Shard iterator type for Kinesis GET operations.
- */
-export type KinesisShardIteratorType =
-  | "AT_SEQUENCE_NUMBER"
-  | "AFTER_SEQUENCE_NUMBER"
-  | "AT_TIMESTAMP"
-  | "TRIM_HORIZON"
-  | "LATEST";
-
-/**
- * Parameters for a Kinesis PUT operation.
- */
-export interface KinesisPutParams {
-  /** The data payload (JSON string or raw string) */
-  data: string;
-  /** The partition key for the record */
-  partitionKey: string;
-  /** How to identify the stream */
-  streamIdentifierType?: KinesisStreamIdentifier;
-  /** Stream name (when streamIdentifierType is STREAM_NAME) */
-  streamName?: string;
-  /** Stream ARN (when streamIdentifierType is STREAM_ARN) */
-  streamArn?: string;
-}
-
-/**
- * Parameters for a Kinesis GET operation.
- */
-export interface KinesisGetParams {
-  /** The shard ID to read from */
-  shardId: string;
-  /** How to position the shard iterator */
-  shardIteratorType: KinesisShardIteratorType;
-  /** Maximum number of records to return */
-  limit?: number;
-  /** Polling cooldown in milliseconds */
-  pollingCooldownMs?: number;
-  /** Starting sequence number (for AT/AFTER_SEQUENCE_NUMBER) */
-  startingSequenceNumber?: string;
-  /** Timestamp (for AT_TIMESTAMP) */
-  timestamp?: string;
-  /** How to identify the stream */
-  streamIdentifierType?: KinesisStreamIdentifier;
-  /** Stream name (when streamIdentifierType is STREAM_NAME) */
-  streamName?: string;
-  /** Stream ARN (when streamIdentifierType is STREAM_ARN) */
-  streamArn?: string;
-}
-
-/**
- * Kinesis client for Amazon Kinesis Data Streams.
- *
- * Provides methods for putting records to and getting records from Kinesis streams.
- *
- * @example
- * ```typescript
- * // Declare in api(): integrations: { kinesis: kinesis(INTEGRATION_ID) }
- * // In run(), access via ctx.integrations.kinesis
- *
- * // Put a record
- * await kinesis.putRecord({
- *   data: JSON.stringify({ event: 'user_signup', userId: '123' }),
- *   partitionKey: 'user-123',
- *   streamName: 'user-events',
- * });
- *
- * // Get records from a shard
- * const records = await kinesis.getRecords({
- *   shardId: 'shardId-000000000000',
- *   shardIteratorType: 'LATEST',
- *   streamName: 'user-events',
- *   limit: 10,
- * });
- * ```
- */
-export interface KinesisClient extends BaseIntegrationClient {
-  /**
-   * Put a record to a Kinesis stream.
-   *
-   * @param params - PUT operation parameters
-   * @returns The raw result from Kinesis (includes ShardId and SequenceNumber)
-   */
-  putRecord(
-    params: KinesisPutParams,
-    metadata?: TraceMetadata,
-  ): Promise<unknown>;
-
-  /**
-   * Get records from a Kinesis stream shard.
-   *
-   * @param params - GET operation parameters
-   * @param metadata - Optional trace metadata for diagnostics
-   * @returns The raw result from Kinesis (includes Records array)
-   */
-  getRecords(
-    params: KinesisGetParams,
-    metadata?: TraceMetadata,
-  ): Promise<unknown>;
-}