# 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/)