@attrove/sdk 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,247 @@
+# @attrove/sdk
+
+Official TypeScript SDK for the Attrove API. Access AI-powered context from your users' Gmail, Slack, Google Calendar, and more.
+
+## Installation
+
+```bash
+npm install @attrove/sdk
+# or
+yarn add @attrove/sdk
+# or
+pnpm add @attrove/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Attrove } from '@attrove/sdk';
+
+// Create a client
+const attrove = new Attrove({
+  apiKey: 'sk_...',  // API key from your dashboard
+  userId: 'user-uuid' // User ID from provisioning
+});
+
+// Query user's context
+const response = await attrove.query('What meetings do I have tomorrow?');
+console.log(response.answer);
+
+// Search for specific information
+const results = await attrove.search('quarterly report');
+```
+
+## Core Methods
+
+### `query(prompt, options?)`
+
+Ask questions about the user's unified context with AI-generated answers.
+
+```typescript
+// Simple query
+const response = await attrove.query('What did Sarah say about the Q4 budget?');
+console.log(response.answer);
+
+// Multi-turn conversation - pass history from previous response
+let history = response.history;
+const followUp = await attrove.query('What about Q3?', { history });
+// Update history for subsequent queries
+history = followUp.history;
+
+// With filters
+const filtered = await attrove.query('Latest updates', {
+  integrationIds: ['integration-uuid'],  // Only search specific integration
+  includeSources: true                   // Include source snippets
+});
+```
+
+### `search(query, options?)`
+
+Semantic search that returns raw messages without AI summarization.
+
+```typescript
+const results = await attrove.search('product launch', {
+  afterDate: '2024-01-01T00:00:00Z',
+  senderDomains: ['acme.com'],
+  includeBodyText: true
+});
+
+for (const [convId, conv] of Object.entries(results.conversations)) {
+  console.log(`Conversation: ${conv.conversation_name}`);
+}
+```
+
+## Resource Namespaces
+
+### Users
+
+```typescript
+// Get user profile and integrations
+const { user, integrations } = await attrove.users.get();
+
+// Update user profile
+await attrove.users.update({
+  timezone: 'America/New_York'
+});
+
+// Get sync statistics
+const stats = await attrove.users.syncStats();
+console.log(`Messages: ${stats.totals.messages.count}`);
+```
+
+### Messages
+
+```typescript
+// List messages
+const { data, pagination } = await attrove.messages.list({
+  limit: 20,
+  expand: ['body_text']
+});
+
+// Get specific messages (e.g., after a query)
+const { data: messages } = await attrove.messages.list({
+  ids: response.used_message_ids,
+  expand: ['body_text']
+});
+
+// Get a single message by ID
+const message = await attrove.messages.get('message-uuid');
+```
+
+### Conversations
+
+```typescript
+// List conversations
+const { data: conversations } = await attrove.conversations.list({
+  syncedOnly: true
+});
+
+// Update sync settings
+await attrove.conversations.updateSync([
+  { id: 'conversation-uuid-1', importMessages: true },
+  { id: 'conversation-uuid-2', importMessages: false }
+]);
+```
+
+### Integrations
+
+```typescript
+// List integrations
+const integrations = await attrove.integrations.list();
+
+// Disconnect an integration
+await attrove.integrations.disconnect('integration-uuid');
+```
+
+## Server-to-Server (Admin) API
+
+Use the admin client for operations that require partner authentication:
+
+```typescript
+import { Attrove } from '@attrove/sdk';
+
+// Create admin client
+const admin = Attrove.admin({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret'
+});
+
+// Create a user
+const { id, apiKey } = await admin.users.create({
+  email: 'user@example.com',
+  firstName: 'John',
+  lastName: 'Doe'
+});
+
+// Generate integration token for OAuth flow
+const { token: connectToken, expires_at } = await admin.users.createConnectToken(id);
+
+// Use the apiKey for subsequent API calls
+const attrove = new Attrove({ apiKey, userId: id });
+
+// Redirect user to OAuth flow
+// The URL format depends on your deployment - check your dashboard for the exact URL
+// Example: const oauthUrl = `${YOUR_BASE_URL}/connect/gmail?token=${connectToken}`;
+```
+
+## Error Handling
+
+The SDK provides typed errors for better error handling:
+
+```typescript
+import {
+  Attrove,
+  AttroveError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError
+} from '@attrove/sdk';
+
+try {
+  const response = await attrove.query('...');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+  } else if (error instanceof NotFoundError) {
+    console.log('Resource not found');
+  } else if (error instanceof AttroveError) {
+    console.log(`Error: ${error.code} - ${error.message}`);
+  }
+}
+```
+
+## Streaming (Advanced)
+
+For real-time streaming of query responses:
+
+```typescript
+const result = await attrove.stream('What happened in the meeting?', {
+  onChunk: (chunk) => process.stdout.write(chunk),
+  onState: (state) => console.log('State:', state),
+  onEnd: (reason) => console.log('Stream ended:', reason)
+});
+
+console.log('Full answer:', result.answer);
+```
+
+> **Note:** Streaming uses WebSocket connections and requires the same API key authentication as other SDK methods. It is primarily intended for end-user facing applications where progressive display of responses improves the user experience.
+
+## Configuration
+
+```typescript
+const attrove = new Attrove({
+  apiKey: 'sk_...',           // Required: API key
+  userId: 'user-uuid',        // Required: User ID
+  baseUrl: 'https://api.attrove.com',  // Optional: API base URL
+  timeout: 30000,             // Optional: Request timeout (ms)
+  maxRetries: 3               // Optional: Retry attempts
+});
+```
+
+## TypeScript Support
+
+The SDK is fully typed. Import types as needed:
+
+```typescript
+import {
+  QueryOptions,
+  QueryResponse,
+  SearchOptions,
+  SearchResponse,
+  User,
+  Message,
+  Integration,
+  ConversationMessage
+} from '@attrove/sdk';
+```
+
+## Requirements
+
+- Node.js 18.0.0 or later
+- TypeScript 4.7+ (if using TypeScript)
+
+## License
+
+MIT

package/package.json

@@ -1 +1,60 @@
-{"name":"@attrove/sdk","version":"0.0.1"}
+{
+  "name": "@attrove/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the Attrove API - AI-powered context retrieval for your apps",
+  "main": "./cjs/index.js",
+  "module": "./esm/index.js",
+  "types": "./types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/src/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "require": {
+        "types": "./types/src/index.d.ts",
+        "default": "./cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "attrove",
+    "sdk",
+    "api",
+    "ai",
+    "rag",
+    "retrieval-augmented-generation",
+    "context",
+    "llm"
+  ],
+  "author": "Attrove <support@attrove.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/attrove/attrove-js.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs.attrove.com",
+  "bugs": {
+    "url": "https://github.com/attrove/attrove-js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "nx build sdk",
+    "test": "nx test sdk"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "~5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}