// Auto-generated from src/ai-service/skills/system/superblocks-api/references/rest-apis.md
// Do not edit directly - edit the .md file instead
export const content = `# REST API Integrations

Reference documentation for working with REST APIs and OpenAPI integrations in Superblocks.

## REST API vs OpenAPI

**Use RestApi** when:
- Making calls to custom endpoints
- No OpenAPI spec available
- Simple GET/POST operations

**Use OpenApi** when:
- Integration metadata shows \`spec: "openapi"\` or \`specType: "OPEN_API_SPEC"\`
- Working with documented APIs (Stripe, Twilio, etc.)
- Need type-safe operations

## RestApi Class

\`\`\`typescript
import { RestApi } from "@superblocksteam/library";

new RestApi("fetch_data", "rest-integration-id", {
  method: "GET",
  url: "https://api.example.com/data",
  params: { page: "1", limit: "10" },
  headers: { "X-Custom-Header": "value" }
})
\`\`\`

### Dynamic Configuration

\`\`\`typescript
new RestApi("create_item", "rest-id", {
  method: "POST",
  url: ({ baseUrl }: { baseUrl: string }) => \`\${baseUrl}/items\`,
  params: ({ page }: { page: number }) => ({ page: String(page) }),
  headers: ({ authToken }: { authToken: string }) => ({
    "Authorization": \`Bearer \${authToken}\`,
    "Content-Type": "application/json"
  }),
  body: ({ itemData }: { itemData: object }) => JSON.stringify(itemData)
})
\`\`\`

### Common REST Patterns

\`\`\`typescript
// GET with query params
new RestApi("search", "rest-id", {
  method: "GET",
  url: "https://api.example.com/search",
  params: ({ query, page }: { query: string; page: number }) => ({
    q: query,
    page: String(page),
    limit: "20"
  })
})

// POST with JSON body
new RestApi("create", "rest-id", {
  method: "POST",
  url: "https://api.example.com/items",
  headers: { "Content-Type": "application/json" },
  body: ({ data }: { data: object }) => JSON.stringify(data)
})

// PUT for updates
new RestApi("update", "rest-id", {
  method: "PUT",
  url: ({ id }: { id: string }) => \`https://api.example.com/items/\${id}\`,
  headers: { "Content-Type": "application/json" },
  body: ({ data }: { data: object }) => JSON.stringify(data)
})

// DELETE
new RestApi("delete", "rest-id", {
  method: "DELETE",
  url: ({ id }: { id: string }) => \`https://api.example.com/items/\${id}\`
})
\`\`\`

## OpenApi Class

\`\`\`typescript
import { OpenApi } from "@superblocksteam/library";

new OpenApi("list_customers", "stripe-integration-id", {
  operation: "listCustomers",
  params: { limit: 10 }
})
\`\`\`

### OpenAPI Operations

Operation names are defined by the API spec. Common patterns:
- \`list{Resource}\` - List all resources
- \`get{Resource}\` - Get a single resource
- \`create{Resource}\` - Create a resource
- \`update{Resource}\` - Update a resource
- \`delete{Resource}\` - Delete a resource

### Dynamic OpenAPI Params

\`\`\`typescript
new OpenApi("get_customer", "stripe-id", {
  operation: "getCustomer",
  params: ({ customerId }: { customerId: string }) => ({
    customer_id: customerId
  })
})
\`\`\`

## Response Handling

REST and OpenAPI responses are available via \`.output\`:

\`\`\`typescript
new RestApi("fetch", "rest-id", { ... }),

new JavaScript("process", {
  fn: ({ fetch }) => {
    const data = fetch.output;
    // For REST APIs, output is typically the JSON response
    // For OpenAPI, output structure depends on the operation
    return data.items.map(item => item.name);
  }
})
\`\`\`

## Error Handling

HTTP errors (4xx, 5xx) are captured in the output:

\`\`\`typescript
new TryCatch("safe_api_call", {
  try: [
    new RestApi("risky_call", "rest-id", {
      method: "POST",
      url: "https://api.example.com/sensitive"
    })
  ],
  catch: [
    new JavaScript("handle_error", {
      fn: ({ apiError }) => ({
        success: false,
        error: apiError.value.message,
        statusCode: apiError.value.statusCode
      })
    })
  ],
  variables: { error: "apiError" }
})
\`\`\`

## Pagination Patterns

### Cursor-Based Pagination

\`\`\`typescript
new Variables("state", [
  { key: "allItems", value: () => [] },
  { key: "cursor", value: () => null },
  { key: "hasMore", value: () => true }
]),

new Loop("paginate", {
  type: "TYPE_FOREACH",
  over: () => [...Array(100).keys()],
  variables: { item: "_", index: "i" },
  blocks: [
    new Conditional("check_done", {
      if: {
        when: ({ hasMore }) => !hasMore.value,
        then: [new Break("exit", { condition: () => true })]
      }
    }),
    new RestApi("fetch_page", "rest-id", {
      method: "GET",
      url: "https://api.example.com/items",
      params: ({ cursor }) => cursor.value ? { cursor: cursor.value } : {}
    }),
    new JavaScript("accumulate", {
      fn: ({ fetch_page, allItems, cursor, hasMore }) => {
        const response = fetch_page.output;
        allItems.set([...allItems.value, ...response.items]);
        cursor.set(response.nextCursor);
        hasMore.set(!!response.nextCursor);
        return allItems.value;
      }
    })
  ]
})
\`\`\`

### Offset-Based Pagination

\`\`\`typescript
new Variables("state", [
  { key: "allItems", value: () => [] },
  { key: "page", value: () => 0 },
  { key: "hasMore", value: () => true }
]),

new Loop("paginate", {
  type: "TYPE_WHILE",
  condition: ({ hasMore }) => hasMore.value,
  blocks: [
    new RestApi("fetch_page", "rest-id", {
      method: "GET",
      url: "https://api.example.com/items",
      params: ({ page }) => ({
        offset: String(page.value * 100),
        limit: "100"
      })
    }),
    new JavaScript("accumulate", {
      fn: ({ fetch_page, allItems, page, hasMore }) => {
        const items = fetch_page.output.items;
        allItems.set([...allItems.value, ...items]);
        page.set(page.value + 1);
        hasMore.set(items.length === 100);
        return allItems.value;
      }
    })
  ]
})
\`\`\`

## Authentication Patterns

### Bearer Token

\`\`\`typescript
new RestApi("authenticated_call", "rest-id", {
  method: "GET",
  url: "https://api.example.com/secure",
  headers: ({ token }: { token: string }) => ({
    "Authorization": \`Bearer \${token}\`
  })
})
\`\`\`

### API Key

\`\`\`typescript
new RestApi("api_key_call", "rest-id", {
  method: "GET",
  url: "https://api.example.com/data",
  headers: ({ apiKey }: { apiKey: string }) => ({
    "X-API-Key": apiKey
  })
})
\`\`\`

### Basic Auth

\`\`\`typescript
new RestApi("basic_auth_call", "rest-id", {
  method: "GET",
  url: "https://api.example.com/data",
  headers: ({ username, password }: { username: string; password: string }) => ({
    "Authorization": \`Basic \${Buffer.from(\`\${username}:\${password}\`).toString("base64")}\`
  })
})
\`\`\`
`;
//# sourceMappingURL=rest-apis.generated.js.map