@superblocksteam/sdk-api 2.0.102-next.0 → 2.0.102

package/src/integrations/snowflakepostgres/types.ts

@@ -6,7 +6,6 @@
  */
 
 import type { z } from "zod";
-
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/runtime/context.ts

@@ -5,22 +5,22 @@
  * providing access to integrations, logging, and environment.
  */
 
-import type { IntegrationDeclaration } from "../integrations/declarations.js";
-import {
-  createClient,
-  type QueryExecutor,
-  type TraceMetadata,
-} from "../integrations/registry.js";
-import type {
-  IntegrationConfig,
-  IntegrationClientImpl,
-} from "../integrations/types.js";
 import type {
   ApiContext,
   ApiUser,
   Logger,
   AnyIntegrationRef,
 } from "../types.js";
+import type {
+  IntegrationConfig,
+  IntegrationClientImpl,
+} from "../integrations/types.js";
+import type { IntegrationDeclaration } from "../integrations/declarations.js";
+import {
+  createClient,
+  type QueryExecutor,
+  type TraceMetadata,
+} from "../integrations/registry.js";
 import { createDefaultLogger } from "./logger.js";
 
 /**

package/src/runtime/streaming-context.ts

@@ -5,6 +5,16 @@
  * access to integrations (with streaming support), logging, and environment.
  */
 
+import type {
+  ApiContext,
+  ApiUser,
+  Logger,
+  AnyIntegrationRef,
+} from "../types.js";
+import type {
+  IntegrationConfig,
+  IntegrationClientImpl,
+} from "../integrations/types.js";
 import type { IntegrationDeclaration } from "../integrations/declarations.js";
 import {
   createClient,
@@ -12,16 +22,6 @@ import {
   type StreamingQueryExecutor,
   type TraceMetadata,
 } from "../integrations/registry.js";
-import type {
-  IntegrationConfig,
-  IntegrationClientImpl,
-} from "../integrations/types.js";
-import type {
-  ApiContext,
-  ApiUser,
-  Logger,
-  AnyIntegrationRef,
-} from "../types.js";
 import { createDefaultLogger } from "./logger.js";
 
 /**

package/src/runtime/streaming-executor.ts

@@ -10,6 +10,10 @@ import { getIntegrationDeclarations } from "../integrations/declarations.js";
 import type { TraceMetadata } from "../integrations/registry.js";
 import type { IntegrationConfig } from "../integrations/types.js";
 import type { ApiUser } from "../types.js";
+import {
+  createStreamingApiContext,
+  type CreateStreamingContextOptions,
+} from "./streaming-context.js";
 import {
   SdkError,
   InputValidationError,
@@ -17,10 +21,6 @@ import {
   ErrorCode,
   type ErrorCodeType,
 } from "./errors.js";
-import {
-  createStreamingApiContext,
-  type CreateStreamingContextOptions,
-} from "./streaming-context.js";
 
 /**
  * Request to execute a streaming API.

package/src/types.ts

@@ -5,7 +5,6 @@
  */
 
 import type { z } from "zod";
-
 import type {
   IntegrationRef,
   AnyIntegrationRef,

package/src/integrations/lakebase/README.md

@@ -1,242 +0,0 @@
-# Lakebase Client
-
-Execute SQL queries and statements against Lakebase databases with full type safety and runtime validation.
-
-## Methods
-
-| Method                                      | Description                                                                |
-| ------------------------------------------- | -------------------------------------------------------------------------- |
-| `query<T>(sql, schema, params?, metadata?)` | Execute a SELECT query and return validated, typed results                 |
-| `execute(sql, params?, metadata?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
-
-## Usage
-
-### Basic Query with Schema Validation
-
-```typescript
-import { api, z, lakebase } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const LAKEBASE_DB = "a1b2c3d4-5678-90ab-cdef-111111111111";
-
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string(),
-  created_at: z.string(),
-});
-
-export default api({
-  name: "GetUsers",
-  integrations: {
-    db: lakebase(LAKEBASE_DB),
-  },
-  input: z.object({
-    status: z.string(),
-  }),
-  output: z.object({
-    users: z.array(UserSchema),
-  }),
-  async run(ctx, { status }) {
-    const users = await ctx.integrations.db.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
-      UserSchema,
-      [status],
-    );
-
-    return { users };
-  },
-});
-```
-
-### Executing INSERT, UPDATE, DELETE Statements
-
-```typescript
-import { api, z, lakebase } from "@superblocksteam/sdk-api";
-
-const LAKEBASE_DB = "a1b2c3d4-5678-90ab-cdef-111111111111";
-
-export default api({
-  name: "ManageUsers",
-  integrations: {
-    db: lakebase(LAKEBASE_DB),
-  },
-  input: z.object({
-    name: z.string(),
-    email: z.string(),
-  }),
-  output: z.object({ success: z.boolean() }),
-
-  async run(ctx, { name, email }) {
-    // INSERT
-    await ctx.integrations.db.execute(
-      "INSERT INTO users (name, email) VALUES ($1, $2)",
-      [name, email],
-    );
-
-    // UPDATE
-    const updateResult = await ctx.integrations.db.execute(
-      "UPDATE users SET last_login = NOW() WHERE email = $1",
-      [email],
-    );
-    console.log(`Updated ${updateResult.rowCount} rows`);
-
-    // DELETE
-    const deleteResult = await ctx.integrations.db.execute(
-      "DELETE FROM sessions WHERE expires_at < NOW()",
-    );
-    console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
-
-    return { success: true };
-  },
-});
-```
-
-### Query with JOIN
-
-```typescript
-const OrderSchema = z.object({
-  order_id: z.string(),
-  customer_name: z.string(),
-  total: z.string(), // NUMERIC as string
-});
-
-const orders = await ctx.integrations.db.query(
-  `SELECT o.id as order_id, c.name as customer_name, o.total
-   FROM orders o
-   JOIN customers c ON o.customer_id = c.id
-   WHERE o.status = $1`,
-  OrderSchema,
-  ["pending"],
-);
-```
-
-## Trace Metadata
-
-All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling:
-
-```typescript
-const users = await ctx.integrations.db.query(
-  "SELECT * FROM users WHERE status = $1",
-  UserSchema,
-  ["active"],
-  { label: "Fetch active users" },
-);
-
-await ctx.integrations.db.execute(
-  "DELETE FROM sessions WHERE expires_at < NOW()",
-  undefined, // no params
-  { label: "Clean expired sessions" },
-);
-```
-
-When `includeDiagnostics` is enabled, `label` and `description` appear in the trace view. See the [root SDK README](../../../README.md#trace-metadata) for details.
-
-## Common Pitfalls
-
-### Uses `$1` Placeholders (PostgreSQL-Style)
-
-Lakebase uses `$1, $2, ...` for parameter placeholders, following PostgreSQL conventions:
-
-```typescript
-// WRONG - Question-mark placeholders
-const users = await ctx.integrations.db.query(
-  "SELECT * FROM users WHERE name = ? AND status = ?",
-  UserSchema,
-  [name, status],
-);
-
-// CORRECT - Use $1, $2, ... placeholders
-const users = await ctx.integrations.db.query(
-  "SELECT * FROM users WHERE name = $1 AND status = $2",
-  UserSchema,
-  [name, status],
-);
-```
-
-### Schema Parameter is Required
-
-The `query()` method requires a Zod schema for runtime validation:
-
-```typescript
-// WRONG - Missing schema parameter
-const users = await ctx.integrations.db.query(
-  "SELECT * FROM users",
-  [
-    /* params */
-  ], // This is wrong - params are 3rd argument
-);
-
-// CORRECT - Schema is the second parameter
-const users = await ctx.integrations.db.query(
-  "SELECT * FROM users WHERE id = $1",
-  UserSchema, // Schema is required
-  [userId], // Params are optional, third argument
-);
-```
-
-### Use Parameterized Queries to Prevent SQL Injection
-
-Always use `$1, $2, ...` placeholders instead of string interpolation:
-
-```typescript
-// WRONG - SQL injection vulnerability
-const users = await ctx.integrations.db.query(
-  `SELECT * FROM users WHERE name = '${userName}'`, // DANGEROUS!
-  UserSchema,
-);
-
-// CORRECT - Use parameterized queries
-const users = await ctx.integrations.db.query(
-  "SELECT * FROM users WHERE name = $1",
-  UserSchema,
-  [userName], // Safe - value is escaped
-);
-```
-
-### NUMERIC/DECIMAL Values Returned as Strings
-
-Large `NUMERIC` and `DECIMAL` columns are returned as strings to preserve precision:
-
-```typescript
-// WRONG - May lose precision
-const schema = z.object({ price: z.number() });
-
-// CORRECT - Keep as string or transform
-const schema = z.object({
-  price: z.string().transform((val) => parseFloat(val)),
-});
-```
-
-### Handling NULL Values
-
-```typescript
-// WRONG - Will fail if column contains NULL
-const schema = z.object({ bio: z.string() });
-
-// CORRECT - Mark nullable columns
-const schema = z.object({ bio: z.string().nullable() });
-```
-
-## Error Handling
-
-### QueryValidationError
-
-Thrown when query results fail schema validation:
-
-```typescript
-import { QueryValidationError } from "@superblocksteam/sdk-api";
-
-try {
-  const users = await ctx.integrations.db.query(
-    "SELECT * FROM users",
-    UserSchema,
-  );
-} catch (error) {
-  if (error instanceof QueryValidationError) {
-    console.error("Row index:", error.details.rowIndex);
-    console.error("Validation errors:", error.details.errors);
-    console.error("Actual row data:", error.details.row);
-  }
-}
-```

package/src/integrations/restapiintegration/README.md

@@ -1,359 +0,0 @@
-# REST API Integration Client
-
-Make HTTP requests to any REST API configured with a base URL and authentication in the integrations page.
-
-This is the generic REST API Integration plugin. Unlike named integrations (Slack, GitHub, etc.) which target a specific service, this plugin works with **any** HTTP API you configure as an integration.
-
-## Methods
-
-| Method                                         | Description                                      |
-| ---------------------------------------------- | ------------------------------------------------ |
-| `apiRequest(options, schema, metadata?)`       | Make any HTTP request with schema validation     |
-| `streamApiRequest(options, schema, metadata?)` | Stream responses with real-time chunk validation |
-
-## Usage
-
-### Basic GET Request
-
-```typescript
-import { api, z, restApiIntegration } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const MY_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
-
-const UsersResponseSchema = z.object({
-  users: z.array(
-    z.object({
-      id: z.string(),
-      name: z.string(),
-      email: z.string(),
-    }),
-  ),
-});
-
-export default api({
-  name: "FetchUsers",
-  integrations: {
-    myApi: restApiIntegration(MY_API),
-  },
-  input: z.object({}),
-  output: z.object({
-    users: z.array(
-      z.object({ id: z.string(), name: z.string(), email: z.string() }),
-    ),
-  }),
-  async run(ctx) {
-    const result = await ctx.integrations.myApi.apiRequest(
-      {
-        method: "GET",
-        path: "/users",
-        params: { limit: 50 },
-      },
-      { response: UsersResponseSchema },
-    );
-
-    return { users: result.users };
-  },
-});
-```
-
-### POST Request with Body
-
-```typescript
-const CreateRecordSchema = z.object({
-  id: z.string(),
-  created_at: z.string(),
-});
-
-const record = await ctx.integrations.myApi.apiRequest(
-  {
-    method: "POST",
-    path: "/records",
-    body: {
-      title: "New Record",
-      description: "Created via Superblocks",
-      tags: ["automated"],
-    },
-    headers: {
-      "Content-Type": "application/json",
-    },
-  },
-  { response: CreateRecordSchema },
-);
-
-console.log(`Created record: ${record.id}`);
-```
-
-### PATCH/PUT Request
-
-```typescript
-const UpdateResponseSchema = z.object({
-  id: z.string(),
-  updated_at: z.string(),
-});
-
-await ctx.integrations.myApi.apiRequest(
-  {
-    method: "PATCH",
-    path: `/records/${recordId}`,
-    body: {
-      title: "Updated Title",
-      status: "published",
-    },
-    headers: {
-      "Content-Type": "application/json",
-    },
-  },
-  { response: UpdateResponseSchema },
-);
-```
-
-### DELETE Request
-
-```typescript
-await ctx.integrations.myApi.apiRequest(
-  {
-    method: "DELETE",
-    path: `/records/${recordId}`,
-  },
-  { response: z.object({}).passthrough() },
-);
-```
-
-### Search with Query Parameters
-
-```typescript
-const SearchResponseSchema = z.object({
-  items: z.array(
-    z.object({
-      id: z.string(),
-      title: z.string(),
-      score: z.number().optional(),
-    }),
-  ),
-  total: z.number(),
-});
-
-const results = await ctx.integrations.myApi.apiRequest(
-  {
-    method: "GET",
-    path: "/search",
-    params: {
-      q: "my query",
-      page: 1,
-      per_page: 25,
-    },
-  },
-  { response: SearchResponseSchema },
-);
-
-console.log(`Found ${results.total} results`);
-```
-
-### Using Multiple Integrations
-
-You can use multiple REST API Integrations in a single API, each targeting a different service:
-
-```typescript
-import { api, z, restApiIntegration, postgres } from "@superblocksteam/sdk-api";
-
-const EXTERNAL_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
-const INTERNAL_API = "e5f6a7b8-9012-34cd-ef56-222222222222";
-const MY_DB = "c3d4e5f6-7890-12ab-cdef-333333333333";
-
-export default api({
-  name: "SyncData",
-  integrations: {
-    externalApi: restApiIntegration(EXTERNAL_API),
-    internalApi: restApiIntegration(INTERNAL_API),
-    db: postgres(MY_DB),
-  },
-  input: z.object({ query: z.string() }),
-  output: z.object({ synced: z.number() }),
-  async run(ctx, { query }) {
-    // Fetch from external API
-    const external = await ctx.integrations.externalApi.apiRequest(
-      { method: "GET", path: "/data", params: { q: query } },
-      { response: z.object({ items: z.array(z.unknown()) }) },
-    );
-
-    // Push to internal API
-    await ctx.integrations.internalApi.apiRequest(
-      { method: "POST", path: "/import", body: { items: external.items } },
-      { response: z.object({ imported: z.number() }) },
-    );
-
-    return { synced: external.items.length };
-  },
-});
-```
-
-### Streaming Responses
-
-For APIs that return streaming data (e.g., Server-Sent Events), use `streamApiRequest()`:
-
-```typescript
-import { streamingApi, z, restApiIntegration } from "@superblocksteam/sdk-api";
-
-const MY_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
-
-const StreamChunkSchema = z.object({
-  id: z.string(),
-  data: z.string(),
-});
-
-export default streamingApi({
-  integrations: {
-    myApi: restApiIntegration(MY_API),
-  },
-  input: z.object({ prompt: z.string() }),
-  chunk: z.object({ text: z.string() }),
-
-  async *run(ctx, { prompt }) {
-    const stream = ctx.integrations.myApi.streamApiRequest(
-      {
-        method: "POST",
-        path: "/stream",
-        body: { prompt },
-      },
-      { chunk: StreamChunkSchema },
-    );
-
-    for await (const chunk of stream) {
-      yield { text: chunk.data };
-    }
-  },
-});
-```
-
-## 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.
-
-```typescript
-const result = await ctx.integrations.myApi.apiRequest(
-  { method: "GET", path: "/users" },
-  { response: UsersResponseSchema },
-  { label: "myApi.getUsers", description: "Fetch all active users" },
-);
-```
-
-## Common Pitfalls
-
-### No `.request()` Method
-
-The only public methods are `apiRequest()` and `streamApiRequest()`. There is no `.request()` method:
-
-```typescript
-// WRONG - .request() does not exist
-await ctx.integrations.myApi.request({
-  method: "GET",
-  path: "/users",
-});
-
-// CORRECT - Use apiRequest with a response schema
-await ctx.integrations.myApi.apiRequest(
-  { method: "GET", path: "/users" },
-  { response: UsersResponseSchema },
-);
-```
-
-### Response Schema is Required
-
-`apiRequest()` requires a response schema for type safety:
-
-```typescript
-// WRONG - Missing response schema
-const result = await ctx.integrations.myApi.apiRequest({
-  method: "GET",
-  path: "/users",
-});
-
-// CORRECT - Provide a response schema
-const result = await ctx.integrations.myApi.apiRequest(
-  { method: "GET", path: "/users" },
-  { response: z.object({ users: z.array(z.unknown()) }) },
-);
-```
-
-### Use `body` Instead of `JSON.stringify`
-
-The `body` field is automatically serialized. Do not stringify it manually:
-
-```typescript
-// WRONG - Manual stringify
-await ctx.integrations.myApi.apiRequest(
-  {
-    method: "POST",
-    path: "/records",
-    body: JSON.stringify({ title: "New" }),
-  },
-  { response: ResponseSchema },
-);
-
-// CORRECT - Pass object directly
-await ctx.integrations.myApi.apiRequest(
-  {
-    method: "POST",
-    path: "/records",
-    body: { title: "New" },
-  },
-  { response: ResponseSchema },
-);
-```
-
-### Use `params` for Query Parameters
-
-Query parameters go in the `params` field, not in the URL path:
-
-```typescript
-// WRONG - Query params in path
-await ctx.integrations.myApi.apiRequest(
-  { method: "GET", path: "/search?q=hello&limit=10" },
-  { response: ResponseSchema },
-);
-
-// CORRECT - Use params field
-await ctx.integrations.myApi.apiRequest(
-  {
-    method: "GET",
-    path: "/search",
-    params: { q: "hello", limit: 10 },
-  },
-  { response: ResponseSchema },
-);
-```
-
-### Use `.passthrough()` for Flexible Schemas
-
-When the response contains fields you don't need to validate, use `.passthrough()`:
-
-```typescript
-// Strict schema - will reject unknown fields
-const StrictSchema = z.object({ id: z.string() });
-
-// Flexible schema - allows additional fields
-const FlexibleSchema = z.object({ id: z.string() }).passthrough();
-
-// For dynamic responses
-const GenericSchema = z.record(z.unknown());
-```
-
-## Error Handling
-
-```typescript
-import { RestApiValidationError } from "@superblocksteam/sdk-api";
-
-try {
-  const result = await ctx.integrations.myApi.apiRequest(
-    { method: "GET", path: "/users" },
-    { response: UsersResponseSchema },
-  );
-} catch (error) {
-  if (error instanceof RestApiValidationError) {
-    // Response didn't match the schema
-    console.error("Validation failed:", error.details.zodError);
-    console.error("Actual response:", error.details.data);
-  }
-}
-```