@superblocksteam/sdk-api 0.0.6 → 0.0.8

package/src/integrations/restapiintegration/README.md

@@ -0,0 +1,320 @@
+# 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 |
+
+## 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 };
+  },
+});
+```
+
+## 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 method is `apiRequest()`. 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);
+  }
+}
+```

package/src/integrations/restapiintegration/client.test.ts

@@ -0,0 +1,359 @@
+/**
+ * Tests for RestApiIntegrationPluginClientImpl (generic REST API Integration).
+ *
+ * Covers the responseType passthrough:
+ * - default requests keep responseType "json"; callers that pass a
+ *   response schema still get validated results
+ * - the responseType option is forwarded to the orchestrator request
+ * - non-JSON responses (e.g. XML with responseType "text") are returned
+ *   raw when no response schema is provided
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+
+import { ActionResponseType } from "@superblocksteam/shared";
+
+import { RestApiValidationError } from "../../errors.js";
+import type { RestApiResponseType } from "../base/types.js";
+import type { IntegrationConfig } from "../types.js";
+import { RestApiIntegrationPluginClientImpl } from "./client.js";
+
+// ── Wire-contract assertions (verified by `pnpm typecheck`) ────────
+//
+// The responseType strings are sent to the orchestrator as-is; the
+// accepted values are defined by ActionResponseType. This assertion
+// fails compilation if the SDK union drifts outside the wire values.
+//
+// The SDK union is a deliberate subset of the wire values: "auto" and
+// "binary" are implemented by the orchestrator but not exposed (see the
+// RestApiResponseType doc for why), and "raw" is streaming-only.
+const _sdkValuesAreValidWireValues: Exclude<`${ActionResponseType}`, "raw">[] =
+  [] as RestApiResponseType[];
+void _sdkValuesAreValidWireValues;
+
+const TEST_CONFIG: IntegrationConfig = {
+  id: "restapi-test-id",
+  name: "Test REST API",
+  pluginId: "restapiintegration",
+  configuration: {},
+};
+
+const XML_RESPONSE = `<?xml version="1.0"?><note><body>hi</body></note>`;
+
+function createClient(mockResult: unknown) {
+  const executeQuery = vi.fn().mockResolvedValue(mockResult);
+  const client = new RestApiIntegrationPluginClientImpl(
+    TEST_CONFIG,
+    executeQuery,
+  );
+  return { client, executeQuery };
+}
+
+describe("RestApiIntegrationPluginClientImpl", () => {
+  // ── Default JSON behavior (must not regress) ────────────────────
+
+  describe("default JSON behavior", () => {
+    it("sends responseType json when the option is omitted", async () => {
+      const { client, executeQuery } = createClient({ id: "1" });
+
+      await client.apiRequest(
+        { method: "GET", path: "/users" },
+        { response: z.object({ id: z.string() }) },
+      );
+
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({ responseType: "json" }),
+        undefined,
+        undefined,
+      );
+    });
+
+    it("validates the response against the provided schema", async () => {
+      const { client } = createClient({ id: "1", extra: "stripped" });
+
+      const result = await client.apiRequest(
+        { method: "GET", path: "/users" },
+        { response: z.object({ id: z.string() }) },
+      );
+
+      expect(result).toEqual({ id: "1" });
+    });
+
+    it("throws RestApiValidationError when the response does not match the schema", async () => {
+      const { client } = createClient(XML_RESPONSE);
+
+      await expect(
+        client.apiRequest(
+          { method: "GET", path: "/users" },
+          { response: z.object({ id: z.string() }) },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+    });
+  });
+
+  // ── responseType passthrough ────────────────────────────────────
+
+  describe("responseType passthrough", () => {
+    it("forwards responseType text to the orchestrator request", async () => {
+      const { client, executeQuery } = createClient(XML_RESPONSE);
+
+      await client.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        responseType: "text",
+      });
+
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({ responseType: "text" }),
+        undefined,
+        undefined,
+      );
+    });
+
+    it("returns a raw XML string with responseType text and no response schema", async () => {
+      const { client } = createClient(XML_RESPONSE);
+
+      const result = await client.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        responseType: "text",
+      });
+
+      expect(result).toBe(XML_RESPONSE);
+    });
+
+    it("still validates when a response schema is provided alongside responseType", async () => {
+      const { client, executeQuery } = createClient(XML_RESPONSE);
+
+      const result = await client.apiRequest(
+        { method: "GET", path: "/report.xml", responseType: "text" },
+        { response: z.string() },
+      );
+
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({ responseType: "text" }),
+        undefined,
+        undefined,
+      );
+      expect(result).toBe(XML_RESPONSE);
+    });
+
+    it("returns the raw response without validation when no schema is given", async () => {
+      const { client } = createClient({ ok: true, rows: [1, 2, 3] });
+
+      const result = await client.apiRequest({
+        method: "GET",
+        path: "/data",
+        responseType: "text",
+      });
+
+      expect(result).toEqual({ ok: true, rows: [1, 2, 3] });
+    });
+
+    it("returns an empty string unchanged for responseType text", async () => {
+      // An empty text body legitimately decodes to "" — the null/undefined
+      // guard must not reject it.
+      const { client } = createClient("");
+
+      const result = await client.apiRequest({
+        method: "GET",
+        path: "/empty",
+        responseType: "text",
+      });
+
+      expect(result).toBe("");
+    });
+
+    it("rejects null and undefined results for every response type", async () => {
+      // Neither value is a legitimate decode result for the exposed
+      // response types: JSON parses to a value the schema sees, and an
+      // empty text body decodes to "". Either means a broken execution
+      // contract, so both throw.
+      for (const badResult of [null, undefined]) {
+        const { client: textClient } = createClient(badResult);
+        await expect(
+          textClient.apiRequest({
+            method: "GET",
+            path: "/broken",
+            responseType: "text",
+          }),
+        ).rejects.toThrow(RestApiValidationError);
+
+        // JSON mode always goes through the schema overload; the bad
+        // result is rejected before validation runs.
+        const { client: jsonClient } = createClient(badResult);
+        await expect(
+          jsonClient.apiRequest(
+            { method: "GET", path: "/broken" },
+            { response: z.object({}) },
+          ),
+        ).rejects.toThrow(RestApiValidationError);
+      }
+    });
+  });
+
+  // ── Request-body validation via the schema-less overload ────────
+
+  describe("request body validation", () => {
+    it("throws RestApiValidationError for an invalid body with a body-only schema", async () => {
+      const { client, executeQuery } = createClient({ ok: true });
+
+      // Runtime-invalid bodies reach this path via dynamic data (user
+      // input, parsed JSON) that the compiler cannot check.
+      const dynamicBody: unknown = JSON.parse('{"amount":"not-a-number"}');
+
+      await expect(
+        client.apiRequest(
+          {
+            method: "POST",
+            path: "/orders",
+            body: dynamicBody,
+            responseType: "text",
+          },
+          { body: z.object({ amount: z.number() }) },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+
+    it("sends a valid body and returns the raw response with a body-only schema", async () => {
+      const { client, executeQuery } = createClient({ ok: true });
+
+      const result = await client.apiRequest(
+        {
+          method: "POST",
+          path: "/orders",
+          body: { amount: 42 },
+          responseType: "text",
+        },
+        { body: z.object({ amount: z.number() }) },
+      );
+
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: JSON.stringify({ amount: 42 }),
+          bodyType: "jsonBody",
+        }),
+        undefined,
+        undefined,
+      );
+      expect(result).toEqual({ ok: true });
+    });
+  });
+
+  // ── Runtime contract enforcement ─────────────────────────────────
+  //
+  // The overloads make these calls unrepresentable in TypeScript, but
+  // user API code executes as esbuild-bundled JS with no type
+  // enforcement — the same contract must hold at runtime.
+
+  describe("runtime contract enforcement", () => {
+    type UncheckedApiRequest = (...args: unknown[]) => Promise<unknown>;
+
+    it("rejects a schema-less call in default JSON mode without issuing the request", async () => {
+      const { client, executeQuery } = createClient({ ok: true });
+
+      await expect(
+        (client.apiRequest as UncheckedApiRequest)({
+          method: "GET",
+          path: "/users",
+        }),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+
+    it("rejects a body-only schema in explicit JSON mode without issuing the request", async () => {
+      const { client, executeQuery } = createClient({ ok: true });
+
+      await expect(
+        (client.apiRequest as UncheckedApiRequest)(
+          {
+            method: "POST",
+            path: "/orders",
+            body: { amount: 42 },
+            responseType: "json",
+          },
+          { body: z.object({ amount: z.number() }) },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+
+    it("rejects an unexposed responseType value without issuing the request", async () => {
+      const { client, executeQuery } = createClient({ ok: true });
+
+      await expect(
+        (client.apiRequest as UncheckedApiRequest)({
+          method: "GET",
+          path: "/report",
+          responseType: "auto",
+        }),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── Compile-time overload contracts (verified by `pnpm typecheck`) ──
+
+  describe("overload resolution", () => {
+    it("keeps typed results for schema callers and unknown for schema-less calls", async () => {
+      const { client } = createClient({ id: "1" });
+
+      // With a response schema: resolves to the typed overload.
+      const typed: Promise<{ id: string }> = client.apiRequest(
+        { method: "GET", path: "/users" },
+        { response: z.object({ id: z.string() }) },
+      );
+      expect(await typed).toEqual({ id: "1" });
+
+      const { client: rawClient } = createClient(XML_RESPONSE);
+
+      // Without a schema: resolves to the raw overload returning unknown.
+      const raw: Promise<unknown> = rawClient.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        responseType: "text",
+      });
+      expect(await raw).toBe(XML_RESPONSE);
+
+      // @ts-expect-error schema-less apiRequest returns unknown, not a typed shape
+      const wrong: Promise<{ id: string }> = rawClient.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        responseType: "text",
+      });
+      await wrong;
+
+      // The remaining cases are rejected twice over: at compile time by
+      // the overloads (@ts-expect-error) and at runtime by the contract
+      // guards, since bundled user code carries no types.
+
+      // @ts-expect-error unvalidated JSON is unrepresentable — schema-less
+      // calls must opt into a non-JSON responseType
+      const unvalidatedJson = rawClient.apiRequest({
+        method: "GET",
+        path: "/users",
+      });
+      await expect(unvalidatedJson).rejects.toThrow(RestApiValidationError);
+
+      // "auto" and "binary" are valid wire values but deliberately not
+      // exposed in the SDK union (see RestApiResponseType).
+      const autoCall = rawClient.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        // @ts-expect-error "auto" is not an exposed responseType
+        responseType: "auto",
+      });
+      await expect(autoCall).rejects.toThrow(RestApiValidationError);
+
+      const binaryCall = rawClient.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        // @ts-expect-error "binary" is not an exposed responseType
+        responseType: "binary",
+      });
+      await expect(binaryCall).rejects.toThrow(RestApiValidationError);
+    });
+  });
+});

package/src/integrations/restapiintegration/docs.manifest.json

@@ -0,0 +1,14 @@
+{
+  "pluginId": "restapiintegration",
+  "base": "README.md",
+  "overlays": [
+    {
+      "file": "overlays/response-types.md",
+      "sdkVersionRange": ">=0.0.3"
+    },
+    {
+      "file": "overlays/response-types-unsupported.md",
+      "sdkVersionRange": "<0.0.3"
+    }
+  ]
+}

package/src/integrations/restapiintegration/overlays/response-types-unsupported.md

@@ -0,0 +1,5 @@
+## Non-JSON Responses
+
+This organization's agent does not support the `responseType` option on `apiRequest()` — its worker runs an sdk-api version that decodes every response as JSON and always requires a response schema. Endpoints returning XML, CSV, or other non-JSON payloads cannot be consumed from SDK APIs until the agent is upgraded.
+
+Do not generate code that passes a `responseType` value: it may typecheck against a newer local copy of the SDK but fails at runtime on this agent with a `RestApiValidationError` (for example, "Integration query returned ... — expected a JSON response object"). If the user needs to consume a non-JSON endpoint, tell them their Superblocks agent must be upgraded first.