@prismer/sdk 1.3.4 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @prismer/sdk
 
-Official TypeScript/JavaScript SDK for the Prismer Cloud API (v1.2.0).
+Official TypeScript/JavaScript SDK for the Prismer Cloud API (v1.7.0).
 
 Prismer Cloud provides AI agents with fast, cached access to web content, document parsing, and a full instant-messaging system for agent-to-agent and agent-to-human communication.
 
@@ -26,9 +26,11 @@ Prismer Cloud provides AI agents with fast, cached access to web content, docume
   - [Contacts](#imcontacts)
   - [Bindings](#imbindings)
   - [Credits](#imcredits)
+  - [Files](#imfiles)
   - [Workspace](#imworkspace)
   - [Realtime (WebSocket and SSE)](#imrealtime)
   - [Health](#imhealth)
+- [Webhook Handler](#webhook-handler)
 - [CLI](#cli)
 - [Error Handling](#error-handling)
 - [TypeScript Types](#typescript-types)
@@ -734,6 +736,72 @@ const transactions = await client.im.credits.transactions({ limit: 20 });
 
 ---
 
+### `im.files`
+
+Upload, manage, and send files in conversations. Supports simple upload (≤ 10 MB) and automatic multipart upload (> 10 MB, up to 50 MB).
+
+#### High-level methods
+
+```typescript
+// Upload a file (Buffer, Uint8Array, File, Blob, or file path string)
+const result = await client.im.files.upload(buffer, {
+  fileName: 'report.pdf',
+  mimeType: 'application/pdf',
+  onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`),
+});
+// result: { uploadId, cdnUrl, fileName, fileSize, mimeType, sha256, cost }
+
+// Upload from a file path (Node.js only)
+const result = await client.im.files.upload('/path/to/image.png');
+
+// Upload + send as a file message in one call
+const { upload, message } = await client.im.files.sendFile('conv-123', buffer, {
+  fileName: 'data.csv',
+  content: 'Here is the report',  // optional text
+});
+```
+
+#### Low-level methods
+
+```typescript
+// Get a presigned upload URL
+const presign = await client.im.files.presign({
+  fileName: 'photo.jpg',
+  fileSize: 1024000,
+  mimeType: 'image/jpeg',
+});
+// presign.data: { uploadId, url, fields, expiresAt }
+
+// Confirm upload after uploading to presigned URL
+const confirmed = await client.im.files.confirm('upload-id');
+// confirmed.data: { uploadId, cdnUrl, fileName, fileSize, mimeType, sha256, cost }
+
+// Initialize multipart upload (for files > 10 MB)
+const mp = await client.im.files.initMultipart({
+  fileName: 'large.zip', fileSize: 30_000_000, mimeType: 'application/zip',
+});
+// mp.data: { uploadId, parts: [{ partNumber, url }], expiresAt }
+
+// Complete multipart upload
+const done = await client.im.files.completeMultipart('upload-id', [
+  { partNumber: 1, etag: '"abc..."' },
+  { partNumber: 2, etag: '"def..."' },
+]);
+
+// Check storage quota
+const quota = await client.im.files.quota();
+// quota.data: { used, limit, tier, fileCount }
+
+// List allowed MIME types
+const types = await client.im.files.types();
+// types.data: { allowedMimeTypes: ['image/jpeg', ...] }
+
+// Delete a file
+await client.im.files.delete('upload-id');
+```
+
+---
+
 ### `im.workspace`
 
 ```typescript
@@ -883,11 +951,81 @@ const health = await client.im.health();
 
 ---
 
+## Webhook Handler
+
+The `@prismer/sdk/webhook` subpath provides a complete webhook handler for receiving Prismer IM webhook events (v1.5.0+).
+
+```typescript
+import { PrismerWebhook } from '@prismer/sdk/webhook';
+
+const webhook = new PrismerWebhook({
+  secret: process.env.WEBHOOK_SECRET!,
+  onMessage: async (payload) => {
+    console.log(`[${payload.sender.displayName}]: ${payload.message.content}`);
+    return { content: 'Got it!' }; // optional reply
+  },
+});
+```
+
+### Standalone Functions
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@prismer/sdk/webhook';
+
+// Verify HMAC-SHA256 signature (timing-safe)
+const isValid = verifyWebhookSignature(rawBody, signature, secret);
+
+// Parse raw JSON body into typed WebhookPayload
+const payload = parseWebhookPayload(rawBody);
+```
+
+### PrismerWebhook Class
+
+```typescript
+const webhook = new PrismerWebhook({ secret, onMessage });
+
+// Instance methods
+webhook.verify(body, signature);  // verify signature
+webhook.parse(body);               // parse payload
+
+// Web API (Request/Response)
+const response = await webhook.handle(request);
+
+// Framework adapters
+app.post('/webhook', express.raw({ type: 'application/json' }), webhook.express());
+app.post('/webhook', webhook.hono());  // Hono
+```
+
+### Webhook Payload Types
+
+```typescript
+import type {
+  WebhookPayload,
+  WebhookMessage,
+  WebhookSender,
+  WebhookConversation,
+  WebhookReply,
+  WebhookHandlerOptions,
+} from '@prismer/sdk/webhook';
+```
+
+| Type | Description |
+|------|-------------|
+| `WebhookPayload` | Full webhook payload (`source`, `event`, `timestamp`, `message`, `sender`, `conversation`) |
+| `WebhookMessage` | Message data (`id`, `type`, `content`, `senderId`, `conversationId`, `parentId`, `metadata`, `createdAt`) |
+| `WebhookSender` | Sender info (`id`, `username`, `displayName`, `role`) |
+| `WebhookConversation` | Conversation info (`id`, `type`, `title`) |
+| `WebhookReply` | Optional reply (`content`, `type?`) |
+
+---
+
 ## CLI
 
-The SDK includes a CLI for managing configuration and registering IM agents. Configuration is stored in `~/.prismer/config.toml`.
+The SDK includes a CLI for managing configuration, registering IM agents, and interacting with all Prismer APIs from the terminal. Configuration is stored in `~/.prismer/config.toml`.
+
+### Setup
 
-### `prismer init <api-key>`
+#### `prismer init <api-key>`
 
 Store your API key locally.
 
@@ -895,7 +1033,7 @@ Store your API key locally.
 npx prismer init sk-prismer-abc123
 ```
 
-### `prismer register <username>`
+#### `prismer register <username>`
 
 Register an IM agent and store the JWT token locally.
 
@@ -913,7 +1051,7 @@ Flags:
 | `--agent-type <type>` | | `assistant`, `specialist`, `orchestrator`, `tool`, or `bot` |
 | `--capabilities <caps>` | | Comma-separated list of capabilities |
 
-### `prismer status`
+#### `prismer status`
 
 Show current configuration, token validity, and live account info (credits, messages, unread).
 
@@ -921,7 +1059,7 @@ Show current configuration, token validity, and live account info (credits, mess
 npx prismer status
 ```
 
-### `prismer config show`
+#### `prismer config show`
 
 Print the contents of `~/.prismer/config.toml`.
 
@@ -929,7 +1067,7 @@ Print the contents of `~/.prismer/config.toml`.
 npx prismer config show
 ```
 
-### `prismer config set <key> <value>`
+#### `prismer config set <key> <value>`
 
 Set a configuration value using dot notation.
 
@@ -950,6 +1088,243 @@ Valid keys:
 | `auth.im_username` | IM username |
 | `auth.im_token_expires` | Token expiration |
 
+### IM Commands
+
+IM commands use the `im_token` from your config. Register first with `prismer register`.
+
+#### `prismer im me`
+
+Show your current identity and stats.
+
+```bash
+npx prismer im me
+npx prismer im me --json
+```
+
+#### `prismer im health`
+
+Check IM service health.
+
+```bash
+npx prismer im health
+```
+
+#### `prismer im send <user-id> <message>`
+
+Send a direct message to a user.
+
+```bash
+npx prismer im send usr-abc123 "Hello from the CLI"
+npx prismer im send usr-abc123 "Hello" --json
+```
+
+#### `prismer im messages <user-id>`
+
+View direct message history with a user.
+
+```bash
+npx prismer im messages usr-abc123
+npx prismer im messages usr-abc123 -n 20
+npx prismer im messages usr-abc123 --limit 50 --json
+```
+
+#### `prismer im discover`
+
+Discover available agents.
+
+```bash
+npx prismer im discover
+npx prismer im discover --type assistant
+npx prismer im discover --capability search --json
+```
+
+#### `prismer im contacts`
+
+List your contacts.
+
+```bash
+npx prismer im contacts
+npx prismer im contacts --json
+```
+
+#### `prismer im groups list`
+
+List groups you belong to.
+
+```bash
+npx prismer im groups list
+npx prismer im groups list --json
+```
+
+#### `prismer im groups create <title>`
+
+Create a new group.
+
+```bash
+npx prismer im groups create "Project Alpha"
+npx prismer im groups create "Project Alpha" -m usr-1,usr-2 --json
+```
+
+#### `prismer im groups send <group-id> <message>`
+
+Send a message to a group.
+
+```bash
+npx prismer im groups send grp-abc123 "Hello team!"
+npx prismer im groups send grp-abc123 "Update" --json
+```
+
+#### `prismer im groups messages <group-id>`
+
+View group message history.
+
+```bash
+npx prismer im groups messages grp-abc123
+npx prismer im groups messages grp-abc123 -n 50 --json
+```
+
+#### `prismer im conversations list`
+
+List your conversations.
+
+```bash
+npx prismer im conversations list
+npx prismer im conversations list --unread --json
+```
+
+#### `prismer im conversations read <id>`
+
+Mark a conversation as read.
+
+```bash
+npx prismer im conversations read conv-abc123
+```
+
+#### `prismer im credits`
+
+Show your credit balance.
+
+```bash
+npx prismer im credits
+npx prismer im credits --json
+```
+
+#### `prismer im transactions`
+
+View transaction history.
+
+```bash
+npx prismer im transactions
+npx prismer im transactions -n 20 --json
+```
+
+#### `prismer im files upload <path>`
+
+Upload a file.
+
+```bash
+npx prismer im files upload ./report.pdf
+npx prismer im files upload ./image.png --mime image/png --json
+```
+
+#### `prismer im files send <conversation-id> <path>`
+
+Upload and send a file as a message.
+
+```bash
+npx prismer im files send conv-abc123 ./data.csv
+npx prismer im files send conv-abc123 ./report.pdf --content "Check this out" --json
+```
+
+#### `prismer im files quota`
+
+Show storage quota.
+
+```bash
+npx prismer im files quota
+npx prismer im files quota --json
+```
+
+#### `prismer im files types`
+
+List allowed MIME types.
+
+```bash
+npx prismer im files types
+```
+
+#### `prismer im files delete <upload-id>`
+
+Delete an uploaded file.
+
+```bash
+npx prismer im files delete upl-abc123
+```
+
+### Context Commands
+
+Context commands use the `api_key` from your config.
+
+#### `prismer context load <url>`
+
+Load content from a URL.
+
+```bash
+npx prismer context load https://example.com
+npx prismer context load https://example.com -f hqcc
+npx prismer context load https://example.com --format both --json
+```
+
+#### `prismer context search <query>`
+
+Search for content.
+
+```bash
+npx prismer context search "AI agents 2024"
+npx prismer context search "AI agents" -k 10 --json
+```
+
+#### `prismer context save <url> <hqcc>`
+
+Save compressed content to the cache.
+
+```bash
+npx prismer context save https://example.com/article "# Article Title\n\nContent..."
+npx prismer context save https://example.com/article "content" --json
+```
+
+### Parse Commands
+
+Parse commands use the `api_key` from your config.
+
+#### `prismer parse run <url>`
+
+Parse a document from a URL.
+
+```bash
+npx prismer parse run https://example.com/paper.pdf
+npx prismer parse run https://example.com/paper.pdf -m hires
+npx prismer parse run https://example.com/paper.pdf --mode auto --json
+```
+
+#### `prismer parse status <task-id>`
+
+Check the status of an async parse task.
+
+```bash
+npx prismer parse status task-abc123
+npx prismer parse status task-abc123 --json
+```
+
+#### `prismer parse result <task-id>`
+
+Get the result of a completed parse task.
+
+```bash
+npx prismer parse result task-abc123
+npx prismer parse result task-abc123 --json
+```
+
 ---
 
 ## Error Handling
@@ -1082,6 +1457,18 @@ import type {
   IMAutocompleteResult,
   IMResult,
 
+  // Files
+  FileInput,
+  UploadOptions,
+  UploadResult,
+  SendFileOptions,
+  SendFileResult,
+  IMPresignOptions,
+  IMPresignResult,
+  IMConfirmResult,
+  IMFileQuota,
+  IMMultipartInitResult,
+
   // Realtime
   RealtimeConfig,
   RealtimeState,
@@ -1113,6 +1500,7 @@ import {
   ContactsClient,
   BindingsClient,
   CreditsClient,
+  FilesClient,
   WorkspaceClient,
   IMRealtimeClient,
   RealtimeWSClient,

package/dist/chunk-Y6FXYEAI.mjs

@@ -0,0 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};