@superblocksteam/sdk-api 0.0.4

package/src/integrations/stripe/README.md

@@ -0,0 +1,453 @@
+# Stripe Client
+
+Process payments, manage customers, and interact with Stripe's payment platform.
+
+## Methods
+
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Stripe API request with schema validation |
+
+## 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
+const customer = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "GET",
+    path: `/v1/customers/${customerId}`,
+  },
+  { response: CustomerSchema },
+);
+
+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
+const ChargeSchema = z.object({
+  id: z.string(),
+  object: z.literal("charge"),
+  amount: z.number(),
+  currency: z.string(),
+  status: z.string(), // succeeded, pending, failed
+  customer: z.string().nullable(),
+  created: z.number(),
+  paid: z.boolean(),
+  refunded: z.boolean(),
+});
+
+const ListChargesSchema = z.object({
+  object: z.literal("list"),
+  data: z.array(ChargeSchema),
+  has_more: z.boolean(),
+  url: z.string(),
+});
+
+const charges = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "GET",
+    path: "/v1/charges",
+    params: {
+      customer: customerId,
+      limit: 10,
+    },
+  },
+  { response: ListChargesSchema },
+);
+
+charges.data.forEach((charge) => {
+  console.log(`${charge.id}: $${charge.amount / 100} - ${charge.status}`);
+});
+```
+
+### 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
+const ProductSchema = z.object({
+  id: z.string(),
+  object: z.literal("product"),
+  name: z.string(),
+  description: z.string().nullable(),
+  active: z.boolean(),
+  metadata: z.record(z.string()),
+});
+
+const ListProductsSchema = z.object({
+  object: z.literal("list"),
+  data: z.array(ProductSchema),
+  has_more: z.boolean(),
+});
+
+const products = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "GET",
+    path: "/v1/products",
+    params: {
+      active: true,
+      limit: 25,
+    },
+  },
+  { response: ListProductsSchema },
+);
+```
+
+### 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.
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await stripe.createCustomer({ ... });
+await stripe.createPaymentIntent({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.stripe.apiRequest(
+  { method: "POST", path: "/v1/customers", body: { ... } },
+  { response: CustomerSchema }
+);
+```
+
+### API Versioning
+
+Stripe has API versions. Set the header for consistent behavior:
+
+```typescript
+const result = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/customers",
+    body: { ... },
+    headers: {
+      "Stripe-Version": "2023-10-16", // Pin to specific version
+    },
+  },
+  { response: CustomerSchema }
+);
+```
+
+### Amounts in Cents
+
+All amounts are in the smallest currency unit (cents for USD):
+
+```typescript
+// WRONG - Dollar amount
+const body = { amount: 20.0 }; // $20.00
+
+// CORRECT - Cents
+const body = { amount: 2000 }; // $20.00 = 2000 cents
+```
+
+### Expandable Objects
+
+Many Stripe responses include expandable objects:
+
+```typescript
+// Default - Returns only ID
+const response = { customer: "cus_123" };
+
+// With expand - Returns full object
+const body = {
+  expand: ["customer", "latest_invoice.payment_intent"],
+};
+// Response: { customer: { id: "cus_123", email: "...", ... } }
+```
+
+### Idempotency Keys
+
+For safe retries, use idempotency keys:
+
+```typescript
+const result = await ctx.integrations.stripe.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/payment_intents",
+    body: { ... },
+    headers: {
+      "Idempotency-Key": "unique-key-for-this-request",
+    },
+  },
+  { response: PaymentIntentSchema }
+);
+```
+
+### Pagination
+
+Stripe uses cursor-based pagination:
+
+```typescript
+async function getAllCustomers(stripe: StripeClient) {
+  const allCustomers: Customer[] = [];
+  let startingAfter: string | undefined;
+
+  while (true) {
+    const result = await ctx.integrations.stripe.apiRequest(
+      {
+        method: "GET",
+        path: "/v1/customers",
+        params: {
+          limit: 100,
+          ...(startingAfter && { starting_after: startingAfter }),
+        },
+      },
+      { response: ListCustomersSchema },
+    );
+
+    allCustomers.push(...result.data);
+    if (!result.has_more) break;
+    startingAfter = result.data[result.data.length - 1].id;
+  }
+
+  return allCustomers;
+}
+```
+
+### Metadata
+
+Metadata values must be strings:
+
+```typescript
+// WRONG - Non-string values
+const metadata = {
+  count: 5,
+  active: true,
+};
+
+// CORRECT - String values only
+const metadata = {
+  count: "5",
+  active: "true",
+};
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.stripe.apiRequest(
+    { method: "POST", path: "/v1/customers", body: { ... } },
+    { response: CustomerSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Stripe API Documentation](https://stripe.com/docs/api)
+- [Customers](https://stripe.com/docs/api/customers)
+- [Payment Intents](https://stripe.com/docs/api/payment_intents)
+- [Subscriptions](https://stripe.com/docs/api/subscriptions)
+- [Error Handling](https://stripe.com/docs/api/errors)

package/src/integrations/stripe/client.ts

@@ -0,0 +1,24 @@
+/**
+ * Stripe client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Stripe integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { StripeClient } from "./types.js";
+
+/**
+ * Internal implementation of StripeClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Stripe API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class StripeClientImpl
+  extends RestApiIntegrationClient
+  implements StripeClient {
+  // Inherits: name, pluginId, config, executeQuery, createParam(), apiRequest()
+  // Can add Stripe-specific methods here in the future if needed
+}

package/src/integrations/stripe/index.ts

@@ -0,0 +1,2 @@
+export { StripeClientImpl } from "./client.js";
+export type { StripeClient } from "./types.js";

package/src/integrations/stripe/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Stripe client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+
+/**
+ * Stripe client for payments and subscriptions.
+ *
+ * Provides the generic apiRequest() method for any Stripe API endpoint.
+ * Use this to interact with Stripe's customers, payments, subscriptions, and other endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * // Declare in api(): integrations: { stripe: stripe(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.stripe
+ *
+ * // Define schemas
+ * const CustomerSchema = z.object({
+ *   id: z.string(),
+ *   email: z.string().email(),
+ *   name: z.string().optional(),
+ *   created: z.number(),
+ * });
+ *
+ * const CreateCustomerRequestSchema = z.object({
+ *   email: z.string().email(),
+ *   name: z.string().optional(),
+ * });
+ *
+ * // Get a customer
+ * const customer = await ctx.integrations.stripe.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/v1/customers/cus_123',
+ *   },
+ *   { response: CustomerSchema }
+ * );
+ *
+ * // Create a customer
+ * const newCustomer = await ctx.integrations.stripe.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/v1/customers',
+ *     body: {
+ *       email: 'customer@example.com',
+ *       name: 'John Doe',
+ *     },
+ *   },
+ *   {
+ *     body: CreateCustomerRequestSchema,
+ *     response: CustomerSchema,
+ *   }
+ * );
+ * ```
+ */
+export interface StripeClient
+  extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}

package/src/integrations/superblocks-ocr/README.md

@@ -0,0 +1,179 @@
+# Superblocks OCR Client
+
+Extract text from images using the Superblocks OCR service with full type safety and runtime validation.
+
+## Methods
+
+| Method                                   | Description                                     |
+| ---------------------------------------- | ----------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any OCR API request with schema validation |
+
+## Usage
+
+### Extract Text from Image URL
+
+```typescript
+import { api, z, superblocksOcr } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_OCR = "a1b2c3d4-5678-90ab-cdef-sbocr0000001";
+
+const OCRResponseSchema = z.object({
+  text: z.string(),
+  confidence: z.number(),
+  blocks: z
+    .array(
+      z.object({
+        text: z.string(),
+        boundingBox: z.object({
+          x: z.number(),
+          y: z.number(),
+          width: z.number(),
+          height: z.number(),
+        }),
+      }),
+    )
+    .optional(),
+});
+
+export default api({
+  integrations: {
+    ocr: superblocksOcr(PROD_OCR),
+  },
+  name: "SuperblocksOCRExample",
+  input: z.object({
+    imageUrl: z.string().url(),
+  }),
+  output: z.object({
+    text: z.string(),
+    confidence: z.number(),
+  }),
+  async run(ctx, { imageUrl }) {
+    const result = await ctx.integrations.ocr.apiRequest(
+      {
+        method: "POST",
+        path: "/extract",
+        body: {
+          imageUrl: imageUrl,
+        },
+      },
+      { response: OCRResponseSchema },
+    );
+
+    return {
+      text: result.text,
+      confidence: result.confidence,
+    };
+  },
+});
+```
+
+### Extract with Options
+
+```typescript
+const result = await ctx.integrations.ocr.apiRequest(
+  {
+    method: "POST",
+    path: "/extract",
+    body: {
+      imageUrl: imageUrl,
+      options: {
+        language: "eng",
+        detectOrientation: true,
+        enhanceImage: true,
+      },
+    },
+  },
+  { response: OCRResponseSchema },
+);
+```
+
+### Extract from Base64 Image
+
+```typescript
+const result = await ctx.integrations.ocr.apiRequest(
+  {
+    method: "POST",
+    path: "/extract",
+    body: {
+      imageBase64: base64ImageData,
+      mimeType: "image/png",
+    },
+  },
+  { response: OCRResponseSchema },
+);
+```
+
+### Get Structured Data
+
+```typescript
+const StructuredResponseSchema = z.object({
+  text: z.string(),
+  tables: z
+    .array(
+      z.object({
+        rows: z.array(z.array(z.string())),
+      }),
+    )
+    .optional(),
+  keyValuePairs: z.record(z.string()).optional(),
+});
+
+const result = await ctx.integrations.ocr.apiRequest(
+  {
+    method: "POST",
+    path: "/extract/structured",
+    body: {
+      imageUrl: imageUrl,
+      extractTables: true,
+      extractKeyValuePairs: true,
+    },
+  },
+  { response: StructuredResponseSchema },
+);
+```
+
+## 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.
+
+## Common Pitfalls
+
+### Image Format
+
+Supported image formats typically include PNG, JPEG, GIF, and BMP.
+
+### Image Size
+
+Large images may take longer to process. Consider resizing before sending.
+
+### Response Schema is Required
+
+```typescript
+// CORRECT - Response schema is required
+await ctx.integrations.ocr.apiRequest(
+  { method: "POST", path: "/extract", body: { ... } },
+  { response: ResponseSchema }
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.ocr.apiRequest(
+    { method: "POST", path: "/extract", body: { ... } },
+    { response: ResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Superblocks Documentation](https://docs.superblocks.com/)