@superblocksteam/sdk-api 0.0.4

package/src/api/definition.test.ts

@@ -0,0 +1,378 @@
+/**
+ * Tests for API definition utility types and entry point mechanism.
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { z } from "zod";
+import {
+  api,
+  __setEntryPoint,
+  consumeEntryPoint,
+  type ExtractApiInput,
+  type ExtractApiOutput,
+} from "./definition.js";
+
+describe("ExtractApiInput", () => {
+  it("extracts input type from simple API", () => {
+    const _SimpleApi = api({
+      name: "SimpleApi",
+      input: z.object({
+        name: z.string(),
+        age: z.number(),
+      }),
+      output: z.object({
+        message: z.string(),
+      }),
+      async run() {
+        return { message: "hello" };
+      },
+    });
+
+    type Input = ExtractApiInput<typeof _SimpleApi>;
+
+    expectTypeOf<Input>().toEqualTypeOf<{
+      name: string;
+      age: number;
+    }>();
+  });
+
+  it("extracts input type with optional fields", () => {
+    const _ApiWithOptional = api({
+      name: "ApiWithOptional",
+      input: z.object({
+        email: z.string().optional(),
+        name: z.string().optional(),
+      }),
+      output: z.object({
+        success: z.boolean(),
+      }),
+      async run() {
+        return { success: true };
+      },
+    });
+
+    type Input = ExtractApiInput<typeof _ApiWithOptional>;
+
+    expectTypeOf<Input>().toEqualTypeOf<{
+      email?: string;
+      name?: string;
+    }>();
+  });
+
+  it("extracts input type with nested objects", () => {
+    const _ApiWithNested = api({
+      name: "ApiWithNested",
+      input: z.object({
+        user: z.object({
+          id: z.string(),
+          profile: z.object({
+            bio: z.string(),
+          }),
+        }),
+      }),
+      output: z.object({
+        result: z.string(),
+      }),
+      async run() {
+        return { result: "ok" };
+      },
+    });
+
+    type Input = ExtractApiInput<typeof _ApiWithNested>;
+
+    expectTypeOf<Input>().toEqualTypeOf<{
+      user: {
+        id: string;
+        profile: {
+          bio: string;
+        };
+      };
+    }>();
+  });
+
+  it("extracts input type with arrays", () => {
+    const _ApiWithArray = api({
+      name: "ApiWithArray",
+      input: z.object({
+        tags: z.array(z.string()),
+        items: z.array(
+          z.object({
+            id: z.number(),
+            name: z.string(),
+          }),
+        ),
+      }),
+      output: z.object({
+        count: z.number(),
+      }),
+      async run() {
+        return { count: 0 };
+      },
+    });
+
+    type Input = ExtractApiInput<typeof _ApiWithArray>;
+
+    expectTypeOf<Input>().toEqualTypeOf<{
+      tags: string[];
+      items: Array<{
+        id: number;
+        name: string;
+      }>;
+    }>();
+  });
+});
+
+describe("ExtractApiOutput", () => {
+  it("extracts output type from simple API", () => {
+    const _SimpleApi = api({
+      name: "SimpleApi",
+      input: z.object({
+        name: z.string(),
+      }),
+      output: z.object({
+        greeting: z.string(),
+        timestamp: z.number(),
+      }),
+      async run() {
+        return { greeting: "hello", timestamp: Date.now() };
+      },
+    });
+
+    type Output = ExtractApiOutput<typeof _SimpleApi>;
+
+    expectTypeOf<Output>().toEqualTypeOf<{
+      greeting: string;
+      timestamp: number;
+    }>();
+  });
+
+  it("extracts output type with complex nested structure", () => {
+    const _ComplexApi = api({
+      name: "ComplexApi",
+      input: z.object({
+        userId: z.string(),
+      }),
+      output: z.object({
+        user: z.object({
+          id: z.string(),
+          email: z.string(),
+          profile: z.object({
+            firstName: z.string(),
+            lastName: z.string(),
+            age: z.number().optional(),
+          }),
+        }),
+        metadata: z.object({
+          createdAt: z.string(),
+          updatedAt: z.string(),
+        }),
+      }),
+      async run() {
+        return {
+          user: {
+            id: "1",
+            email: "test@example.com",
+            profile: {
+              firstName: "John",
+              lastName: "Doe",
+            },
+          },
+          metadata: {
+            createdAt: "2024-01-01",
+            updatedAt: "2024-01-01",
+          },
+        };
+      },
+    });
+
+    type Output = ExtractApiOutput<typeof _ComplexApi>;
+
+    expectTypeOf<Output>().toEqualTypeOf<{
+      user: {
+        id: string;
+        email: string;
+        profile: {
+          firstName: string;
+          lastName: string;
+          age?: number;
+        };
+      };
+      metadata: {
+        createdAt: string;
+        updatedAt: string;
+      };
+    }>();
+  });
+
+  it("extracts output type with arrays", () => {
+    const _ListApi = api({
+      name: "ListApi",
+      input: z.object({
+        limit: z.number(),
+      }),
+      output: z.object({
+        items: z.array(
+          z.object({
+            id: z.string(),
+            name: z.string(),
+          }),
+        ),
+        total: z.number(),
+      }),
+      async run() {
+        return { items: [], total: 0 };
+      },
+    });
+
+    type Output = ExtractApiOutput<typeof _ListApi>;
+
+    expectTypeOf<Output>().toEqualTypeOf<{
+      items: Array<{
+        id: string;
+        name: string;
+      }>;
+      total: number;
+    }>();
+  });
+
+  it("extracts output type with union types", () => {
+    const _UnionApi = api({
+      name: "UnionApi",
+      input: z.object({
+        query: z.string(),
+      }),
+      output: z.object({
+        status: z.union([z.literal("success"), z.literal("error")]),
+        data: z.string().optional(),
+        error: z.string().optional(),
+      }),
+      async run() {
+        return { status: "success" as const };
+      },
+    });
+
+    type Output = ExtractApiOutput<typeof _UnionApi>;
+
+    expectTypeOf<Output>().toEqualTypeOf<{
+      status: "success" | "error";
+      data?: string;
+      error?: string;
+    }>();
+  });
+});
+
+describe("ExtractApiInput and ExtractApiOutput together", () => {
+  it("correctly extracts both input and output types", () => {
+    const _FullApi = api({
+      name: "FullApi",
+      input: z.object({
+        userId: z.string().uuid(),
+        includeDetails: z.boolean().optional(),
+      }),
+      output: z.object({
+        user: z.object({
+          id: z.string(),
+          name: z.string(),
+          email: z.string().email(),
+        }),
+        details: z
+          .object({
+            lastLogin: z.string(),
+            accountType: z.enum(["free", "premium"]),
+          })
+          .optional(),
+      }),
+      async run() {
+        return {
+          user: {
+            id: "1",
+            name: "John",
+            email: "john@example.com",
+          },
+        };
+      },
+    });
+
+    type Input = ExtractApiInput<typeof _FullApi>;
+    type Output = ExtractApiOutput<typeof _FullApi>;
+
+    expectTypeOf<Input>().toEqualTypeOf<{
+      userId: string;
+      includeDetails?: boolean;
+    }>();
+
+    expectTypeOf<Output>().toEqualTypeOf<{
+      user: {
+        id: string;
+        name: string;
+        email: string;
+      };
+      details?: {
+        lastLogin: string;
+        accountType: "free" | "premium";
+      };
+    }>();
+  });
+});
+
+describe("entryPoint mechanism", () => {
+  it("api() has no entryPoint when __setEntryPoint was not called", () => {
+    const compiled = api({
+      name: "NoEntryPoint",
+      input: z.object({}),
+      output: z.object({ ok: z.boolean() }),
+      async run() {
+        return { ok: true };
+      },
+    });
+
+    expect(compiled.entryPoint).toBeUndefined();
+  });
+
+  it("api() picks up entryPoint set via __setEntryPoint", () => {
+    __setEntryPoint("server/apis/GetUsers/api.ts");
+    const compiled = api({
+      name: "GetUsers",
+      input: z.object({}),
+      output: z.object({ users: z.array(z.string()) }),
+      async run() {
+        return { users: [] };
+      },
+    });
+
+    expect(compiled.entryPoint).toBe("server/apis/GetUsers/api.ts");
+  });
+
+  it("consumeEntryPoint clears the pending value", () => {
+    __setEntryPoint("server/apis/Temp/api.ts");
+    const first = consumeEntryPoint();
+    const second = consumeEntryPoint();
+
+    expect(first).toBe("server/apis/Temp/api.ts");
+    expect(second).toBeUndefined();
+  });
+
+  it("entryPoint is consumed once — second api() call gets undefined", () => {
+    __setEntryPoint("server/apis/First/api.ts");
+    const first = api({
+      name: "First",
+      input: z.object({}),
+      output: z.object({}),
+      async run() {
+        return {};
+      },
+    });
+    const second = api({
+      name: "Second",
+      input: z.object({}),
+      output: z.object({}),
+      async run() {
+        return {};
+      },
+    });
+
+    expect(first.entryPoint).toBe("server/apis/First/api.ts");
+    expect(second.entryPoint).toBeUndefined();
+  });
+});

package/src/api/definition.ts

@@ -0,0 +1,210 @@
+/**
+ * API definition function.
+ *
+ * This module provides the `api()` function used to define TypeScript-based APIs
+ * with input/output validation using Zod schemas and upfront integration declarations.
+ */
+
+import type { z } from "zod";
+
+/**
+ * Extract the input type from a CompiledApi.
+ *
+ * Use this utility type to extract input types from API definitions for use in the frontend
+ * without importing the runtime API code.
+ *
+ * @example
+ * ```typescript
+ * import type GetUsersApi from '../server/apis/GetUsers/api';
+ * import type { ExtractApiInput } from '@superblocksteam/sdk-api';
+ *
+ * type GetUsersInput = ExtractApiInput<typeof GetUsersApi>;
+ * // GetUsersInput is now { email?: string; name?: string; }
+ * ```
+ */
+export type ExtractApiInput<T> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends CompiledApi<infer TInput, any> ? TInput : never;
+
+/**
+ * Extract the output type from a CompiledApi.
+ *
+ * Use this utility type to extract output types from API definitions for use in the frontend
+ * without importing the runtime API code.
+ *
+ * @example
+ * ```typescript
+ * import type GetUsersApi from '../server/apis/GetUsers/api';
+ * import type { ExtractApiOutput } from '@superblocksteam/sdk-api';
+ *
+ * type GetUsersOutput = ExtractApiOutput<typeof GetUsersApi>;
+ * // GetUsersOutput is now { users: User[]; }
+ * ```
+ */
+export type ExtractApiOutput<T> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends CompiledApi<any, infer TOutput> ? TOutput : never;
+import type { ApiConfig, ApiContext, AnyIntegrationRef } from "../types.js";
+import {
+  extractIntegrationDeclarations,
+  type IntegrationDeclaration,
+} from "../integrations/declarations.js";
+
+// ---------------------------------------------------------------------------
+// Entry point setter — used by the Vite plugin to stamp the source file path
+// onto the next api()/streamingApi() call. ESM top-level execution is
+// synchronous, so the prepended __setEntryPoint() always runs before api().
+// ---------------------------------------------------------------------------
+
+let __pendingEntryPoint: string | undefined;
+
+/** Called by the Vite plugin to set the entry point for the next api() call. */
+export function __setEntryPoint(entryPoint: string): void {
+  __pendingEntryPoint = entryPoint;
+}
+
+export function consumeEntryPoint(): string | undefined {
+  const ep = __pendingEntryPoint;
+  __pendingEntryPoint = undefined;
+  return ep;
+}
+
+/**
+ * A compiled API definition ready for execution.
+ *
+ * @template TInput - The inferred input type
+ * @template TOutput - The inferred output type
+ */
+export interface CompiledApi<TInput = unknown, TOutput = unknown> {
+  /** Name of the API for identification in logs and debugging */
+  readonly name: string;
+
+  /** Plain-language summary of what this API does */
+  readonly description?: string;
+  /**
+   * Source file path relative to the app root (e.g. "server/apis/GetUsers/api.ts").
+   * Injected automatically by the Vite plugin — not authored by the user.
+   */
+  readonly entryPoint?: string;
+
+  /** Zod schema for validating inputs */
+  readonly inputSchema: z.ZodType<TInput>;
+
+  /** Zod schema for validating outputs */
+  readonly outputSchema: z.ZodType<TOutput>;
+
+  /**
+   * The API implementation function.
+   *
+   * @param ctx - Execution context
+   * @param input - Validated input parameters
+   * @returns Promise resolving to the output
+   */
+  readonly run: (
+    ctx: ApiContext<Record<string, AnyIntegrationRef>>,
+    input: TInput,
+  ) => Promise<TOutput>;
+
+  /**
+   * Declared integrations for upfront authentication.
+   *
+   * This array contains all integrations declared in the API config,
+   * allowing the runtime to authenticate them before API execution.
+   *
+   * @example
+   * ```typescript
+   * // Given an API with:
+   * // integrations: { db: postgres('Prod DB'), notifier: slack('Ops Slack') }
+   * //
+   * // compiledApi.integrations would be:
+   * // [
+   * //   { key: 'db', pluginId: 'postgres', name: 'Prod DB' },
+   * //   { key: 'notifier', pluginId: 'slack', name: 'Ops Slack' },
+   * // ]
+   * ```
+   */
+  readonly integrations: ReadonlyArray<IntegrationDeclaration>;
+}
+
+/**
+ * Define a TypeScript-based API with input/output validation.
+ *
+ * This function creates a compiled API definition that can be executed
+ * by the Superblocks runtime. Inputs and outputs are validated using
+ * the provided Zod schemas.
+ *
+ * @param config - The API configuration
+ * @returns A compiled API definition
+ *
+ * @example
+ * ```typescript
+ * import { api, z, postgres, slack } from '@superblocksteam/sdk-api';
+ *
+ * export default api({
+ *   name: 'GetUser',
+ *   integrations: {
+ *     db: postgres('Production Postgres'),
+ *     notifier: slack('Ops Slack'),
+ *   },
+ *
+ *   input: z.object({
+ *     userId: z.string().uuid(),
+ *   }),
+ *
+ *   output: z.object({
+ *     user: z.object({
+ *       id: z.string(),
+ *       name: z.string(),
+ *       email: z.string().email(),
+ *     }),
+ *   }),
+ *
+ *   async run(ctx, { userId }) {
+ *     const [user] = await ctx.integrations.db.query(
+ *       'SELECT * FROM users WHERE id = $1',
+ *       z.object({ id: z.string(), name: z.string(), email: z.string() }),
+ *       [userId]
+ *     );
+ *
+ *     if (!user) {
+ *       throw new Error('User not found');
+ *     }
+ *
+ *     await ctx.integrations.notifier.postMessage({
+ *       channel: '#user-lookups',
+ *       text: `Fetched user ${user.name}`,
+ *     });
+ *
+ *     return { user };
+ *   },
+ * });
+ * ```
+ */
+export function api<
+  TInput extends z.ZodType,
+  TOutput extends z.ZodType,
+  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
+    string,
+    never
+  >,
+>(
+  config: ApiConfig<TInput, TOutput, TIntegrations>,
+): CompiledApi<z.infer<TInput>, z.infer<TOutput>> {
+  // Extract integration declarations for upfront auth
+  const integrations = extractIntegrationDeclarations(config.integrations);
+
+  const compiled: CompiledApi<z.infer<TInput>, z.infer<TOutput>> = {
+    name: config.name,
+    description: config.description,
+    entryPoint: consumeEntryPoint(),
+    inputSchema: config.input,
+    outputSchema: config.output,
+    run: config.run as (
+      ctx: ApiContext<Record<string, AnyIntegrationRef>>,
+      input: z.infer<TInput>,
+    ) => Promise<z.infer<TOutput>>,
+    integrations,
+  };
+
+  return compiled;
+}

package/src/api/index.ts

@@ -0,0 +1,10 @@
+/**
+ * API definition module.
+ */
+
+export { api, __setEntryPoint } from "./definition.js";
+export type { CompiledApi } from "./definition.js";
+
+// Streaming API support
+export { streamingApi, isStreamingApi } from "./streaming.js";
+export type { StreamingApiConfig, CompiledStreamingApi } from "./streaming.js";