@superblocksteam/sdk-api 0.0.12-body-types → 0.0.13

package/src/integrations/stripe/README.md

@@ -10,57 +10,6 @@ Process payments, manage customers, and interact with Stripe's payment platform.
 
 ## Usage
 
-### Create a Customer
-
-```typescript
-import { api, z, stripe } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_STRIPE = "a1b2c3d4-5678-90ab-cdef-stripe000001";
-
-const CustomerSchema = z.object({
-  id: z.string(),
-  object: z.literal("customer"),
-  email: z.string().nullable(),
-  name: z.string().nullable(),
-  created: z.number(),
-  metadata: z.record(z.string()),
-  default_source: z.string().nullable(),
-});
-
-export default api({
-  name: "StripeExample",
-  integrations: {
-    stripe: stripe(PROD_STRIPE),
-  },
-  input: z.object({
-    email: z.string().email(),
-    name: z.string(),
-  }),
-  output: z.object({
-    customerId: z.string(),
-  }),
-  async run(ctx, { email, name }) {
-    const result = await ctx.integrations.stripe.apiRequest(
-      {
-        method: "POST",
-        path: "/v1/customers",
-        body: {
-          email: email,
-          name: name,
-          metadata: {
-            source: "api",
-          },
-        },
-      },
-      { response: CustomerSchema },
-    );
-
-    return { customerId: result.id };
-  },
-});
-```
-
 ### Get a Customer
 
 ```typescript
@@ -75,43 +24,6 @@ const customer = await ctx.integrations.stripe.apiRequest(
 console.log(`Customer: ${customer.name} (${customer.email})`);
 ```
 
-### Create a Payment Intent
-
-```typescript
-const PaymentIntentSchema = z.object({
-  id: z.string(),
-  object: z.literal("payment_intent"),
-  amount: z.number(),
-  currency: z.string(),
-  status: z.string(),
-  client_secret: z.string(),
-  customer: z.string().nullable(),
-  metadata: z.record(z.string()),
-});
-
-const paymentIntent = await ctx.integrations.stripe.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/payment_intents",
-    body: {
-      amount: 2000, // Amount in cents ($20.00)
-      currency: "usd",
-      customer: customerId,
-      automatic_payment_methods: {
-        enabled: true,
-      },
-      metadata: {
-        order_id: "order_123",
-      },
-    },
-  },
-  { response: PaymentIntentSchema },
-);
-
-// Return client_secret to frontend for Stripe.js
-console.log(`Client secret: ${paymentIntent.client_secret}`);
-```
-
 ### List Charges
 
 ```typescript
@@ -151,67 +63,6 @@ charges.data.forEach((charge) => {
 });
 ```
 
-### Create a Subscription
-
-```typescript
-const SubscriptionSchema = z.object({
-  id: z.string(),
-  object: z.literal("subscription"),
-  customer: z.string(),
-  status: z.string(), // active, past_due, canceled, etc.
-  current_period_start: z.number(),
-  current_period_end: z.number(),
-  items: z.object({
-    data: z.array(
-      z.object({
-        id: z.string(),
-        price: z.object({ id: z.string() }),
-      }),
-    ),
-  }),
-});
-
-const subscription = await ctx.integrations.stripe.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/subscriptions",
-    body: {
-      customer: customerId,
-      items: [{ price: "price_abc123" }],
-      payment_behavior: "default_incomplete",
-      expand: ["latest_invoice.payment_intent"],
-    },
-  },
-  { response: SubscriptionSchema },
-);
-```
-
-### Create a Refund
-
-```typescript
-const RefundSchema = z.object({
-  id: z.string(),
-  object: z.literal("refund"),
-  amount: z.number(),
-  charge: z.string(),
-  status: z.string(), // succeeded, pending, failed, canceled
-  created: z.number(),
-});
-
-const refund = await ctx.integrations.stripe.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/refunds",
-    body: {
-      charge: chargeId,
-      amount: 1000, // Partial refund of $10.00
-      reason: "requested_by_customer",
-    },
-  },
-  { response: RefundSchema },
-);
-```
-
 ### List Products
 
 ```typescript
@@ -243,58 +94,6 @@ const products = await ctx.integrations.stripe.apiRequest(
 );
 ```
 
-### Create Invoice
-
-```typescript
-const InvoiceSchema = z.object({
-  id: z.string(),
-  object: z.literal("invoice"),
-  customer: z.string(),
-  status: z.string(), // draft, open, paid, uncollectible, void
-  total: z.number(),
-  amount_due: z.number(),
-  hosted_invoice_url: z.string().nullable(),
-});
-
-const invoice = await ctx.integrations.stripe.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/invoices",
-    body: {
-      customer: customerId,
-      collection_method: "send_invoice",
-      days_until_due: 30,
-    },
-  },
-  { response: InvoiceSchema },
-);
-
-// Add line items
-await ctx.integrations.stripe.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/invoiceitems",
-    body: {
-      customer: customerId,
-      invoice: invoice.id,
-      amount: 5000,
-      currency: "usd",
-      description: "Consulting services",
-    },
-  },
-  { response: z.object({ id: z.string() }) },
-);
-
-// Finalize and send
-await ctx.integrations.stripe.apiRequest(
-  {
-    method: "POST",
-    path: `/v1/invoices/${invoice.id}/finalize`,
-  },
-  { response: InvoiceSchema },
-);
-```
-
 ## 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.

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

@@ -1,5 +1,14 @@
 {
   "pluginId": "stripe",
   "base": "README.md",
-  "overlays": []
+  "overlays": [
+    {
+      "file": "overlays/request-bodies.md",
+      "sdkVersionRange": ">=0.0.7"
+    },
+    {
+      "file": "overlays/request-bodies-unsupported.md",
+      "sdkVersionRange": "<0.0.7"
+    }
+  ]
 }

package/src/integrations/stripe/overlays/request-bodies-unsupported.md

@@ -0,0 +1,3 @@
+## Creating Customers, Payment Intents, Subscriptions, Refunds, and Invoices
+
+Stripe rejects any request whose body is not `application/x-www-form-urlencoded`. This agent's sdk-api cannot send that encoding through `apiRequest()` because it serializes every body as JSON, so creating a customer, payment intent, subscription, refund, or invoice always fails. Do not generate Stripe write code until the agent is upgraded. Getting a customer, listing charges, and listing products work as documented above; they send no body.

package/src/integrations/stripe/overlays/request-bodies.md

@@ -0,0 +1,204 @@
+## Creating Customers, Payment Intents, Subscriptions, Refunds, and Invoices
+
+Stripe expects `application/x-www-form-urlencoded` bodies, not JSON, so pass `bodyType: "formUrlencoded"` on every write request. Flatten nested fields with bracket notation, such as `"metadata[order_id]"`. An array field whose API name ends in `[]`, such as `expand`, needs the brackets in the key: `"expand[]": [...]`. The SDK adds `Content-Type: application/x-www-form-urlencoded` unless you already provided a `Content-Type` header.
+
+### Create a Customer
+
+```typescript
+import { api, z, stripe } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_STRIPE = "a1b2c3d4-5678-90ab-cdef-stripe000001";
+
+const CustomerSchema = z.object({
+  id: z.string(),
+  object: z.literal("customer"),
+  email: z.string().nullable(),
+  name: z.string().nullable(),
+  created: z.number(),
+  metadata: z.record(z.string()),
+  default_source: z.string().nullable(),
+});
+
+export default api({
+  name: "StripeExample",
+  integrations: {
+    stripe: stripe(PROD_STRIPE),
+  },
+  input: z.object({
+    email: z.string().email(),
+    name: z.string(),
+  }),
+  output: z.object({
+    customerId: z.string(),
+  }),
+  async run(ctx, { email, name }) {
+    const result = await ctx.integrations.stripe.apiRequest(
+      {
+        method: "POST",
+        path: "/v1/customers",
+        bodyType: "formUrlencoded",
+        body: {
+          email: email,
+          name: name,
+          "metadata[source]": "api",
+        },
+      },
+      { response: CustomerSchema },
+    );
+
+    return { customerId: result.id };
+  },
+});
+```
+
+### Create a Payment Intent
+
+```typescript
+const PaymentIntentSchema = z.object({
+  id: z.string(),
+  object: z.literal("payment_intent"),
+  amount: z.number(),
+  currency: z.string(),
+  status: z.string(),
+  client_secret: z.string(),
+  customer: z.string().nullable(),
+  metadata: z.record(z.string()),
+});
+
+const paymentIntent = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/payment_intents",
+    bodyType: "formUrlencoded",
+    body: {
+      amount: 2000, // Amount in cents ($20.00)
+      currency: "usd",
+      customer: customerId,
+      "automatic_payment_methods[enabled]": true,
+      "metadata[order_id]": "order_123",
+    },
+  },
+  { response: PaymentIntentSchema },
+);
+
+// Return client_secret to frontend for Stripe.js
+console.log(`Client secret: ${paymentIntent.client_secret}`);
+```
+
+### Create a Subscription
+
+```typescript
+const SubscriptionSchema = z.object({
+  id: z.string(),
+  object: z.literal("subscription"),
+  customer: z.string(),
+  status: z.string(), // active, past_due, canceled, etc.
+  current_period_start: z.number(),
+  current_period_end: z.number(),
+  items: z.object({
+    data: z.array(
+      z.object({
+        id: z.string(),
+        price: z.object({ id: z.string() }),
+      }),
+    ),
+  }),
+});
+
+const subscription = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/subscriptions",
+    bodyType: "formUrlencoded",
+    body: {
+      customer: customerId,
+      "items[0][price]": "price_abc123",
+      payment_behavior: "default_incomplete",
+      "expand[]": ["latest_invoice.payment_intent"],
+    },
+  },
+  { response: SubscriptionSchema },
+);
+```
+
+### Create a Refund
+
+```typescript
+const RefundSchema = z.object({
+  id: z.string(),
+  object: z.literal("refund"),
+  amount: z.number(),
+  charge: z.string(),
+  status: z.string(), // succeeded, pending, failed, canceled
+  created: z.number(),
+});
+
+const refund = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/refunds",
+    bodyType: "formUrlencoded",
+    body: {
+      charge: chargeId,
+      amount: 1000, // Partial refund of $10.00
+      reason: "requested_by_customer",
+    },
+  },
+  { response: RefundSchema },
+);
+```
+
+### Create Invoice
+
+```typescript
+const InvoiceSchema = z.object({
+  id: z.string(),
+  object: z.literal("invoice"),
+  customer: z.string(),
+  status: z.string(), // draft, open, paid, uncollectible, void
+  total: z.number(),
+  amount_due: z.number(),
+  hosted_invoice_url: z.string().nullable(),
+});
+
+const invoice = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/invoices",
+    bodyType: "formUrlencoded",
+    body: {
+      customer: customerId,
+      collection_method: "send_invoice",
+      days_until_due: 30,
+    },
+  },
+  { response: InvoiceSchema },
+);
+
+// Add line items
+await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/invoiceitems",
+    bodyType: "formUrlencoded",
+    body: {
+      customer: customerId,
+      invoice: invoice.id,
+      amount: 5000,
+      currency: "usd",
+      description: "Consulting services",
+    },
+  },
+  { response: z.object({ id: z.string() }) },
+);
+
+// Finalize and send; this call has no body
+await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: `/v1/invoices/${invoice.id}/finalize`,
+  },
+  { response: InvoiceSchema },
+);
+```

package/src/integrations/utils.ts

@@ -1,7 +1,23 @@
+import { z } from "zod";
+
+import { isBinaryData, RestApiValidationError } from "../errors.js";
+
+const MAX_OPTION_VALUE_CHARS = 64;
+
 /**
  * Integration utility functions.
  */
 
+/**
+ * Truncates a string to at most `max` characters, appending "..." when it
+ * was cut. The single place that defines how caller-supplied strings are
+ * bounded for display (`describeType`, `describeOptionValue`) and for the
+ * Zod issue `path` (`boundedPathSegment`).
+ */
+function truncate(value: string, max = MAX_OPTION_VALUE_CHARS): string {
+  return value.length > max ? `${value.slice(0, max)}...` : value;
+}
+
 /**
  * Produces a safe, human-readable description of a value's type
  * without exposing potentially sensitive data.
@@ -18,8 +34,42 @@ export function describeType(value: unknown): string {
   if (t === "object") {
     const keys = Object.keys(value as Record<string, unknown>);
     if (keys.length === 0) return "empty object";
-    return `object with keys [${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", ..." : ""}]`;
+    const shown = keys.slice(0, 5).map((k) => truncate(k));
+    return `object with keys [${shown.join(", ")}${keys.length > 5 ? ", ..." : ""}]`;
   }
 
   return t;
 }
+
+/**
+ * Describes a caller-supplied option value for an error message with bounded
+ * length. Strings are quoted and truncated; everything else is described by type
+ * so arbitrary payloads never land in the message.
+ */
+export function describeOptionValue(value: unknown): string {
+  if (isBinaryData(value)) {
+    return `binary data (${value.byteLength} bytes)`;
+  }
+  if (typeof value !== "string") return describeType(value);
+  return JSON.stringify(truncate(value));
+}
+
+function boundedPathSegment(segment: string | number): string | number {
+  return typeof segment === "string" ? truncate(segment) : segment;
+}
+
+export function validationError(
+  message: string,
+  path: (string | number)[],
+): RestApiValidationError {
+  return new RestApiValidationError(message, {
+    data: undefined,
+    zodError: new z.ZodError([
+      {
+        code: z.ZodIssueCode.custom,
+        message,
+        path: path.map(boundedPathSegment),
+      },
+    ]),
+  });
+}

package/src/runtime/context.ts

@@ -57,6 +57,13 @@ export interface CreateContextOptions {
   /** Environment variables */
   env: Record<string, string>;
 
+  /**
+   * Server-resolved data tag key.
+   *
+   * Optional for compatibility with execution wrappers from older agents.
+   */
+  dataTag?: string;
+
   /** User information from JWT */
   user: ApiUser;
 
@@ -101,6 +108,7 @@ export function createApiContext(
     executeQuery,
     executionId,
     env,
+    dataTag,
     user,
     logger,
   } = options;
@@ -172,6 +180,7 @@ export function createApiContext(
     >["integrations"],
     log,
     env: Object.freeze({ ...env }),
+    dataTag,
     user,
   };
 }

package/src/runtime/executor.ts

@@ -36,6 +36,13 @@ export interface ExecuteApiRequest {
   /** Environment variables available to the API */
   env: Record<string, string>;
 
+  /**
+   * Server-resolved data tag key for this execution.
+   *
+   * Optional on the low-level request for compatibility with older runtimes.
+   */
+  dataTag?: string;
+
   /** User information extracted from the Superblocks JWT */
   user: ApiUser;
 
@@ -162,6 +169,7 @@ export async function executeApi<TInput = unknown, TOutput = unknown>(
       executeQuery: request.executeQuery,
       executionId: request.executionId,
       env: request.env,
+      dataTag: request.dataTag,
       user: request.user,
     });
 

package/src/types.ts

@@ -182,6 +182,17 @@ export interface ApiContext<
   /** Access to environment variables */
   readonly env: Readonly<Record<string, string>>;
 
+  /**
+   * Canonical key of the requested data tag validated for this execution.
+   *
+   * This identifies the integration configuration in use, not a user's
+   * environment entitlement. It is supplied by the Superblocks runtime and
+   * cannot be selected through API input. It is undefined when no data tag was
+   * resolved or on runtimes that predate data-tag context support;
+   * authorization checks must deny access in those cases.
+   */
+  readonly dataTag?: string;
+
   /** User information from the Superblocks JWT */
   readonly user: ApiUser;
 }