@superblocksteam/sdk-api 0.0.4

package/src/types.ts

@@ -0,0 +1,210 @@
+/**
+ * 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;
+}
+
+// Re-export integration ref type for advanced use cases
+export type { IntegrationRef, AnyIntegrationRef, IntegrationsMap };