> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK

> Scope-enforced tools and audit logging for Vercel AI SDK agents.

## Install

```bash theme={null}
npm install @grantex/vercel-ai @grantex/sdk ai zod
```

## Scope-Enforced Tools

Create Vercel AI SDK tools with Grantex authorization. Scope is checked **at construction time** — if the token is missing the required scope, `createGrantexTool` throws immediately:

```typescript theme={null}
import { createGrantexTool } from '@grantex/vercel-ai';
import { z } from 'zod';

const readCalendar = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  parameters: z.object({
    date: z.string().describe('Date in YYYY-MM-DD format'),
  }),
  grantToken,                     // JWT from Grantex token exchange
  requiredScope: 'calendar:read', // checked at construction time
  execute: async (args) => {
    return await getCalendarEvents(args.date);
  },
});

// Use with generateText, streamText, etc.
import { generateText } from 'ai';

const { text } = await generateText({
  model: openai('gpt-4'),
  tools: { read_calendar: readCalendar },
  prompt: 'What meetings do I have today?',
});
```

## Inspect Grant Scopes

Use `getGrantScopes` to check what scopes a token has before creating tools:

```typescript theme={null}
import { getGrantScopes } from '@grantex/vercel-ai';

const scopes = getGrantScopes(grantToken);
// → ['calendar:read', 'email:send']
```

## Audit Logging

Wrap tools with `withAuditLogging` to log every invocation to the Grantex audit trail:

```typescript theme={null}
import { Grantex } from '@grantex/sdk';
import { createGrantexTool, withAuditLogging } from '@grantex/vercel-ai';

const client = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const audited = withAuditLogging(readCalendar, client, {
  agentId: 'ag_01ABC...',
  agentDid: 'did:key:z6Mk...',
  grantId: 'grnt_01XYZ...',
  principalId: 'user_01',
});
// Use audited in place of readCalendar
```

## API Reference

### `createGrantexTool(options)`

| Option          | Type                                 | Description                                   |
| --------------- | ------------------------------------ | --------------------------------------------- |
| `name`          | `string`                             | Tool name                                     |
| `description`   | `string`                             | Tool description                              |
| `parameters`    | `z.ZodTypeAny`                       | Zod schema for tool arguments                 |
| `grantToken`    | `string`                             | Grantex JWT from token exchange               |
| `requiredScope` | `string`                             | Scope required — checked at construction time |
| `execute`       | `(args, options) => Promise<Result>` | Tool implementation                           |

Throws `GrantexScopeError` if scope is missing.

### `getGrantScopes(grantToken)`

Returns `string[]` of scopes from the token's `scp` claim (offline).

### `withAuditLogging(tool, client, options)`

| Option        | Type      | Description                             |
| ------------- | --------- | --------------------------------------- |
| `agentId`     | `string`  | Agent ID for audit attribution          |
| `agentDid`    | `string`  | Agent DID (e.g. `did:key:z6Mk...`)      |
| `grantId`     | `string`  | Grant ID for the session                |
| `principalId` | `string`  | Principal ID that granted authorization |
| `toolName`    | `string?` | Override tool name in audit entries     |

### `GrantexScopeError`

| Property        | Type       | Description                       |
| --------------- | ---------- | --------------------------------- |
| `requiredScope` | `string`   | The scope that was required       |
| `grantedScopes` | `string[]` | The scopes the token actually has |

## Requirements

* Node.js 18+
* `@grantex/sdk` >= 0.1.0
* `ai` >= 4.0.0 (Vercel AI SDK)
* `zod` >= 3.0.0