@superblocksteam/sdk-api 0.0.4

package/dist/runtime/streaming-executor.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Streaming API execution engine.
+ *
+ * Provides the entry point for executing compiled streaming APIs,
+ * handling input validation, chunk validation, and error management.
+ */
+import type { CompiledStreamingApi } from "../api/streaming.js";
+import type { TraceMetadata } from "../integrations/registry.js";
+import type { IntegrationConfig } from "../integrations/types.js";
+import type { ApiUser } from "../types.js";
+import { type ErrorCodeType } from "./errors.js";
+/**
+ * Request to execute a streaming API.
+ */
+export interface ExecuteStreamingApiRequest {
+    /** Raw input data to be validated */
+    input: unknown;
+    /** Available integration configurations */
+    integrations: IntegrationConfig[];
+    /** Unique execution ID for tracing */
+    executionId: string;
+    /** Environment variables available to the API */
+    env: Record<string, string>;
+    /** User information extracted from the Superblocks JWT */
+    user: ApiUser;
+    /**
+     * Function to execute integration operations (non-streaming).
+     *
+     * @param integrationId - The integration ID
+     * @param request - Plugin-specific request object
+     * @param bindings - Optional bindings for language plugins
+     * @returns Promise resolving to the operation result
+     */
+    executeQuery: (integrationId: string, request: Record<string, unknown>, bindings?: Record<string, unknown>, metadata?: TraceMetadata) => Promise<unknown>;
+    /**
+     * Function to execute streaming integration operations.
+     *
+     * @param integrationId - The integration ID
+     * @param request - Plugin-specific request object
+     * @param metadata - Optional trace metadata for diagnostics
+     * @returns AsyncIterable yielding raw chunks
+     */
+    executeStreamingQuery?: (integrationId: string, request: Record<string, unknown>, metadata?: TraceMetadata) => AsyncIterable<unknown>;
+}
+/**
+ * Callback handlers for streaming API execution.
+ */
+export interface StreamingApiCallbacks<TChunk = unknown> {
+    /**
+     * Called for each validated chunk.
+     *
+     * @param chunk - The validated chunk
+     * @param index - Zero-based index of this chunk
+     */
+    onChunk: (chunk: TChunk, index: number) => void;
+    /**
+     * Called when the stream completes successfully.
+     *
+     * @param totalChunks - Total number of chunks yielded
+     */
+    onComplete?: (totalChunks: number) => void;
+    /**
+     * Called when an error occurs.
+     *
+     * @param error - The error that occurred
+     */
+    onError?: (error: StreamingApiError) => void;
+}
+/**
+ * Error details for streaming API execution.
+ */
+export interface StreamingApiError {
+    code: ErrorCodeType;
+    message: string;
+    details?: unknown;
+    /** Number of chunks successfully yielded before the error */
+    chunksYielded?: number;
+}
+/**
+ * Result of streaming API execution.
+ *
+ * Uses a discriminated union to prevent impossible states
+ * like `{ success: true, error: {...} }`.
+ */
+export type ExecuteStreamingApiResult = {
+    success: true;
+    totalChunks: number;
+} | {
+    success: false;
+    totalChunks: number;
+    error: StreamingApiError;
+};
+/**
+ * Executes a compiled streaming API with the given request.
+ *
+ * This function handles:
+ * 1. Input validation against the API's Zod schema
+ * 2. Context creation with integration clients
+ * 3. Iterating over the async generator
+ * 4. Chunk validation against the API's chunk schema
+ * 5. Calling callbacks for chunks, completion, and errors
+ *
+ * @param api - The compiled streaming API definition
+ * @param request - The execution request
+ * @param callbacks - Callbacks for chunks, completion, and errors
+ * @returns Promise resolving to execution result
+ *
+ * @example
+ * ```typescript
+ * import { streamingApi, z, executeStreamingApi } from '@superblocksteam/sdk-api';
+ *
+ * const myApi = streamingApi({
+ *   input: z.object({ prompt: z.string() }),
+ *   chunk: z.object({ text: z.string() }),
+ *   async *run(ctx) {
+ *     yield { text: 'Hello' };
+ *     yield { text: ' World' };
+ *   },
+ * });
+ *
+ * const result = await executeStreamingApi(
+ *   myApi,
+ *   {
+ *     input: { prompt: 'Hi' },
+ *     integrations: [],
+ *     executionId: 'exec_123',
+ *     env: {},
+ *     executeQuery: async () => ({}),
+ *   },
+ *   {
+ *     onChunk: (chunk, index) => console.log(`Chunk ${index}:`, chunk),
+ *     onComplete: (total) => console.log(`Stream completed with ${total} chunks`),
+ *     onError: (error) => console.error('Stream error:', error),
+ *   }
+ * );
+ * ```
+ */
+export declare function executeStreamingApi<TInput = unknown, TChunk = unknown>(api: CompiledStreamingApi<TInput, TChunk>, request: ExecuteStreamingApiRequest, callbacks: StreamingApiCallbacks<TChunk>): Promise<ExecuteStreamingApiResult>;
+/**
+ * Creates an async generator that wraps streaming API execution.
+ *
+ * This is an alternative interface for consuming streaming APIs that returns
+ * an AsyncGenerator directly, rather than using callbacks.
+ *
+ * @param api - The compiled streaming API definition
+ * @param request - The execution request
+ * @returns AsyncGenerator yielding validated chunks
+ *
+ * @example
+ * ```typescript
+ * const generator = createStreamingApiGenerator(myApi, request);
+ *
+ * for await (const chunk of generator) {
+ *   console.log('Received chunk:', chunk);
+ * }
+ * ```
+ */
+export declare function createStreamingApiGenerator<TInput = unknown, TChunk = unknown>(api: CompiledStreamingApi<TInput, TChunk>, request: ExecuteStreamingApiRequest): AsyncGenerator<TChunk, void, undefined>;
+//# sourceMappingURL=streaming-executor.d.ts.map

package/dist/runtime/streaming-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-executor.d.ts","sourceRoot":"","sources":["../../src/runtime/streaming-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAK3C,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IAEf,2CAA2C;IAC3C,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAElC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B,0DAA0D;IAC1D,IAAI,EAAE,OAAO,CAAC;IAEd;;;;;;;OAOG;IACH,YAAY,EAAE,CACZ,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,CAAC,EAAE,aAAa,KACrB,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,CACtB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,CAAC,EAAE,aAAa,KACrB,aAAa,CAAC,OAAO,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,MAAM,GAAG,OAAO;IACrD;;;;;OAKG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3C;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAC1E,GAAG,EAAE,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,OAAO,EAAE,0BAA0B,EACnC,SAAS,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,yBAAyB,CAAC,CAkHpC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuB,2BAA2B,CAChD,MAAM,GAAG,OAAO,EAChB,MAAM,GAAG,OAAO,EAEhB,GAAG,EAAE,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,OAAO,EAAE,0BAA0B,GAClC,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAuDzC"}

package/dist/runtime/streaming-executor.js

@@ -0,0 +1,229 @@
+/**
+ * Streaming API execution engine.
+ *
+ * Provides the entry point for executing compiled streaming APIs,
+ * handling input validation, chunk validation, and error management.
+ */
+import { getIntegrationDeclarations } from "../integrations/declarations.js";
+import { createStreamingApiContext, } from "./streaming-context.js";
+import { SdkError, InputValidationError, ExecutionError, ErrorCode, } from "./errors.js";
+/**
+ * Executes a compiled streaming API with the given request.
+ *
+ * This function handles:
+ * 1. Input validation against the API's Zod schema
+ * 2. Context creation with integration clients
+ * 3. Iterating over the async generator
+ * 4. Chunk validation against the API's chunk schema
+ * 5. Calling callbacks for chunks, completion, and errors
+ *
+ * @param api - The compiled streaming API definition
+ * @param request - The execution request
+ * @param callbacks - Callbacks for chunks, completion, and errors
+ * @returns Promise resolving to execution result
+ *
+ * @example
+ * ```typescript
+ * import { streamingApi, z, executeStreamingApi } from '@superblocksteam/sdk-api';
+ *
+ * const myApi = streamingApi({
+ *   input: z.object({ prompt: z.string() }),
+ *   chunk: z.object({ text: z.string() }),
+ *   async *run(ctx) {
+ *     yield { text: 'Hello' };
+ *     yield { text: ' World' };
+ *   },
+ * });
+ *
+ * const result = await executeStreamingApi(
+ *   myApi,
+ *   {
+ *     input: { prompt: 'Hi' },
+ *     integrations: [],
+ *     executionId: 'exec_123',
+ *     env: {},
+ *     executeQuery: async () => ({}),
+ *   },
+ *   {
+ *     onChunk: (chunk, index) => console.log(`Chunk ${index}:`, chunk),
+ *     onComplete: (total) => console.log(`Stream completed with ${total} chunks`),
+ *     onError: (error) => console.error('Stream error:', error),
+ *   }
+ * );
+ * ```
+ */
+export async function executeStreamingApi(api, request, callbacks) {
+    let totalChunks = 0;
+    try {
+        // 1. Validate input
+        const inputResult = api.inputSchema.safeParse(request.input);
+        if (!inputResult.success) {
+            const error = {
+                code: ErrorCode.INPUT_VALIDATION,
+                message: "Input validation failed",
+                details: { issues: inputResult.error.issues },
+                chunksYielded: 0,
+            };
+            callbacks.onError?.(error);
+            return { success: false, totalChunks: 0, error };
+        }
+        // 2. Build integration map (keyed by id)
+        const integrations = new Map();
+        for (const config of request.integrations) {
+            integrations.set(config.id, config);
+        }
+        // 3. Create execution context with streaming support
+        const contextOptions = {
+            integrations,
+            integrationDeclarations: getIntegrationDeclarations(api),
+            executeQuery: request.executeQuery,
+            executeStreamingQuery: request.executeStreamingQuery,
+            executionId: request.executionId,
+            env: request.env,
+            user: request.user,
+        };
+        const ctx = createStreamingApiContext(contextOptions);
+        // 4. Execute the streaming API
+        let iterator;
+        try {
+            iterator = api.run(ctx, inputResult.data);
+        }
+        catch (err) {
+            if (err instanceof SdkError) {
+                const error = {
+                    code: err.code,
+                    message: err.message,
+                    details: err.details,
+                    chunksYielded: 0,
+                };
+                callbacks.onError?.(error);
+                return { success: false, totalChunks: 0, error };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            const error = {
+                code: ErrorCode.EXECUTION_ERROR,
+                message,
+                details: { cause: err },
+                chunksYielded: 0,
+            };
+            callbacks.onError?.(error);
+            return { success: false, totalChunks: 0, error };
+        }
+        // 5. Iterate over chunks, validate, and call callbacks
+        for await (const rawChunk of iterator) {
+            // Validate chunk against schema
+            const chunkResult = api.chunkSchema.safeParse(rawChunk);
+            if (!chunkResult.success) {
+                const error = {
+                    code: ErrorCode.OUTPUT_VALIDATION,
+                    message: `Chunk validation failed at index ${totalChunks}`,
+                    details: {
+                        issues: chunkResult.error.issues,
+                        chunkIndex: totalChunks,
+                        rawChunk,
+                    },
+                    chunksYielded: totalChunks,
+                };
+                callbacks.onError?.(error);
+                return { success: false, totalChunks, error };
+            }
+            // Call chunk callback
+            callbacks.onChunk(chunkResult.data, totalChunks);
+            totalChunks++;
+        }
+        // 6. Stream completed successfully
+        callbacks.onComplete?.(totalChunks);
+        return { success: true, totalChunks };
+    }
+    catch (err) {
+        // Handle unexpected errors
+        const message = err instanceof Error ? err.message : String(err);
+        let error;
+        if (err instanceof SdkError) {
+            error = {
+                code: err.code,
+                message: err.message,
+                details: err.details,
+                chunksYielded: totalChunks,
+            };
+        }
+        else {
+            error = {
+                code: ErrorCode.INTERNAL_ERROR,
+                message: `Unexpected error: ${message}`,
+                details: err instanceof Error ? { stack: err.stack } : undefined,
+                chunksYielded: totalChunks,
+            };
+        }
+        callbacks.onError?.(error);
+        return { success: false, totalChunks, error };
+    }
+}
+/**
+ * Creates an async generator that wraps streaming API execution.
+ *
+ * This is an alternative interface for consuming streaming APIs that returns
+ * an AsyncGenerator directly, rather than using callbacks.
+ *
+ * @param api - The compiled streaming API definition
+ * @param request - The execution request
+ * @returns AsyncGenerator yielding validated chunks
+ *
+ * @example
+ * ```typescript
+ * const generator = createStreamingApiGenerator(myApi, request);
+ *
+ * for await (const chunk of generator) {
+ *   console.log('Received chunk:', chunk);
+ * }
+ * ```
+ */
+export async function* createStreamingApiGenerator(api, request) {
+    // Validate input
+    const inputResult = api.inputSchema.safeParse(request.input);
+    if (!inputResult.success) {
+        throw new InputValidationError("Input validation failed", {
+            issues: inputResult.error.issues,
+        });
+    }
+    // Build integration map
+    const integrations = new Map();
+    for (const config of request.integrations) {
+        integrations.set(config.id, config);
+    }
+    // Create execution context
+    const ctx = createStreamingApiContext({
+        integrations,
+        integrationDeclarations: getIntegrationDeclarations(api),
+        executeQuery: request.executeQuery,
+        executeStreamingQuery: request.executeStreamingQuery,
+        executionId: request.executionId,
+        env: request.env,
+        user: request.user,
+    });
+    // Execute and yield validated chunks
+    let chunkIndex = 0;
+    try {
+        const iterator = api.run(ctx, inputResult.data);
+        for await (const rawChunk of iterator) {
+            const chunkResult = api.chunkSchema.safeParse(rawChunk);
+            if (!chunkResult.success) {
+                throw new SdkError(ErrorCode.OUTPUT_VALIDATION, `Chunk validation failed at index ${chunkIndex}`, {
+                    issues: chunkResult.error.issues,
+                    chunkIndex,
+                    rawChunk,
+                });
+            }
+            yield chunkResult.data;
+            chunkIndex++;
+        }
+    }
+    catch (err) {
+        if (err instanceof SdkError) {
+            throw err;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ExecutionError(message, err);
+    }
+}
+//# sourceMappingURL=streaming-executor.js.map

package/dist/runtime/streaming-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-executor.js","sourceRoot":"","sources":["../../src/runtime/streaming-executor.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Core type definitions for the Superblocks SDK.
+ *
+ * This module provides the public types used to define TypeScript-based APIs.
+ */
+import type { z } from "zod";
+import type { IntegrationRef, AnyIntegrationRef, IntegrationsMap } from "./integrations/declarations.js";
+/**
+ * Configuration for defining a TypeScript-based API.
+ *
+ * @template TInput - Zod schema type for input validation
+ * @template TOutput - Zod schema type for output validation
+ * @template TIntegrations - Record of integration declarations
+ *
+ * @example
+ * ```typescript
+ * import { api, z, postgres, slack } from '@superblocksteam/sdk-api';
+ *
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ * });
+ *
+ * export default api({
+ *   integrations: {
+ *     db: postgres('Production Postgres'),
+ *     notifier: slack('Ops Slack'),
+ *   },
+ *   input: z.object({ userId: z.string() }),
+ *   output: z.object({ user: UserSchema }),
+ *   async run(ctx, { userId }) {
+ *     const users = await ctx.integrations.db.query(
+ *       'SELECT * FROM users WHERE id = $1',
+ *       UserSchema,  // Schema is REQUIRED
+ *       [userId]
+ *     );
+ *     if (users.length === 0) {
+ *       throw new Error('User not found');
+ *     }
+ *     await ctx.integrations.notifier.postMessage({
+ *       channel: '#alerts',
+ *       text: `Fetched user ${users[0].name}`,
+ *     });
+ *     return { user: users[0] };
+ *   },
+ * });
+ * ```
+ */
+export interface ApiConfig<TInput extends z.ZodType, TOutput extends z.ZodType, TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>> {
+    /**
+     * Name for this API.
+     *
+     * Used for identification in execution logs and debugging.
+     */
+    name: string;
+    /**
+     * Plain-language summary of what this API does and which integrations it uses,
+     * written for a non-technical audience.
+     *
+     * This field is auto-generated by the AI agent when creating or editing an API.
+     */
+    description?: string;
+    /**
+     * Integration declarations for this API.
+     *
+     * Declare integrations upfront to enable type-safe access via `ctx.integrations`
+     * and to allow the runtime to authenticate integrations before execution.
+     *
+     * @example
+     * ```typescript
+     * integrations: {
+     *   db: postgres('Production Postgres'),
+     *   cache: redis('Cache Redis'),
+     * }
+     * ```
+     */
+    integrations?: TIntegrations;
+    /** Zod schema for input validation */
+    input: TInput;
+    /** Zod schema for output validation */
+    output: TOutput;
+    /**
+     * The API implementation function.
+     *
+     * @param ctx - Execution context with access to integrations, logging, and environment
+     * @param input - Validated input parameters (can be destructured)
+     * @returns Promise resolving to the validated output
+     */
+    run: (ctx: ApiContext<TIntegrations>, input: z.infer<TInput>) => Promise<z.infer<TOutput>>;
+}
+/**
+ * User information extracted from the Superblocks JWT.
+ *
+ * This information is passed to the API context and is available
+ * as `ctx.user` in API implementations.
+ */
+export interface ApiUser {
+    /** Unique user identifier from JWT */
+    readonly userId: string;
+    /** User's email address (if available) */
+    readonly email?: string;
+    /** User's display name (if available) */
+    readonly name?: string;
+    /** User's group memberships from JWT */
+    readonly groups: readonly string[];
+    /** Custom claims from JWT */
+    readonly customClaims: Readonly<Record<string, unknown>>;
+}
+/**
+ * Execution context passed to the API run function.
+ *
+ * Provides access to integration clients, logging, environment variables,
+ * and user information.
+ *
+ * @template TIntegrations - Record of integration declarations
+ */
+export interface ApiContext<TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>> {
+    /**
+     * Typed integration clients declared in the API config.
+     *
+     * Access each integration by the name (key) you declared: `ctx.integrations.<name>`.
+     * Each client is fully typed based on the declaration function used.
+     *
+     * @example
+     * ```typescript
+     * // Given: integrations: { db: postgres('My Postgres'), notifier: slack('My Slack') }
+     *
+     * // ctx.integrations.db is PostgresClient
+     * const users = await ctx.integrations.db.query('SELECT * FROM users', UserSchema);
+     *
+     * // ctx.integrations.notifier is SlackClient
+     * await ctx.integrations.notifier.postMessage({ channel: '#alerts', text: 'Hello!' });
+     * ```
+     */
+    readonly integrations: IntegrationsMap<TIntegrations>;
+    /** Logger for structured logging */
+    readonly log: Logger;
+    /** Access to environment variables */
+    readonly env: Readonly<Record<string, string>>;
+    /** User information from the Superblocks JWT */
+    readonly user: ApiUser;
+}
+/**
+ * Logger interface for API execution.
+ *
+ * All log methods accept an optional data object for structured logging.
+ */
+export interface Logger {
+    /** Log an info message */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Log a warning message */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /** Log an error message */
+    error(message: string, data?: Record<string, unknown>): void;
+    /** Log a debug message */
+    debug(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Base interface for all integration clients.
+ */
+export interface BaseIntegrationClient {
+    /** The integration name */
+    readonly name: string;
+    /** The plugin type ID (e.g., 'postgres', 'slack') */
+    readonly pluginId: string;
+}
+export type { IntegrationRef, AnyIntegrationRef, IntegrationsMap };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Core type definitions for the Superblocks SDK.
+ *
+ * This module provides the public types used to define TypeScript-based APIs.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@superblocksteam/sdk-api",
+  "version": "0.0.4",
+  "description": "Superblocks SDK for TypeScript-based API definitions",
+  "license": "Superblocks Community Software License",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@superblocksteam/types": "1.196.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@bufbuild/protobuf": "1.3.0",
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^20",
+    "@types/uuid": "^9.0.0",
+    "dotenv": "^16.4.5",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.47.0",
+    "uuid": "^9.0.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=10.x"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf ./dist *tsbuildinfo",
+    "dev": "tsc --build --watch",
+    "lint": "eslint --max-warnings 0",
+    "lint:fix": "eslint --fix",
+    "publish-package": "pnpm publish",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run --config tests/e2e/vitest.config.ts",
+    "test:e2e:watch": "vitest --config tests/e2e/vitest.config.ts",
+    "test:e2e:setup": "tsx tests/e2e/utils/setup-integrations.ts",
+    "typecheck": "tsc --noEmit",
+    "coverage-matrix": "tsx scripts/generate-coverage-matrix.ts"
+  }
+}