# @intuned/files

Intuned SDK for file operations. Provides helpers for converting files to
markdown and extracting tables from files, backed by the Intuned file APIs.
Must be used within Intuned projects and requires the dependency `@intuned/runtime`.

## Installation

```bash
yarn add @intuned/files
# @intuned/runtime is an optional peer dependency used when running inside the
# Intuned runtime (for auth and tracking).
# @intuned/browser is an optional peer dependency, only needed for the
# `download` file source (see below).
```

## Usage

### Extract markdown

```typescript
import { extractMarkdownFromFile } from "@intuned/files";

const markdown = await extractMarkdownFromFile({
  type: "pdf",
  url: "https://example.com/report.pdf",
});
```

### Extract tables

`extractTablesFromFile` returns each table's page number, title, and cell content.

```typescript
import { extractTablesFromFile } from "@intuned/files";

const tables = await extractTablesFromFile({
  type: "pdf",
  url: "https://example.com/report.pdf",
});
```

### Extract structured data

`extractStructuredDataFromFile` converts the file to markdown and then extracts data
against a schema. It requires the optional `@intuned/browser` peer dependency
(the other operations do not); it throws a clear error at call time if it is
missing.

```typescript
import { extractStructuredDataFromFile } from "@intuned/files";

const data = await extractStructuredDataFromFile(
  { type: "pdf", url: "https://example.com/invoice.pdf" },
  {
    dataSchema: {
      type: "object",
      properties: {
        invoiceNumber: { type: "string" },
        total: { type: "number" },
      },
      required: ["invoiceNumber", "total"],
    },
  },
);
```

`dataSchema` accepts a JSON Schema object or a zod schema.

### File sources

Provide exactly one source key on the file object:

```typescript
await extractMarkdownFromFile({
  type: "pdf",
  url: "https://example.com/report.pdf",
});
await extractMarkdownFromFile({ type: "pdf", base64: "<base64 string>" });
await extractMarkdownFromFile({ type: "pdf", buffer: someBuffer });

// `download` accepts the result of downloadFile from @intuned/browser,
// awaited or not. Requires @intuned/browser to be installed.
import { downloadFile } from "@intuned/browser";
await extractMarkdownFromFile({
  type: "pdf",
  download: downloadFile({ page, trigger }),
});
```

### Supported file types

`pdf`, `image`, `spreadsheet` (`.xlsx`), and `document` (`.docx`). Sources can be
a `url`, a `base64` string, a Node.js `buffer`, or a `download`.

## Development

```bash
yarn install
yarn tsc      # typecheck
yarn lint     # lint
yarn build    # build to dist/
yarn test     # run unit tests
```