@savantoai/ai-sdk 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-2025 Savanto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,280 @@
+# @savantoai/ai-sdk
+
+Official JavaScript/TypeScript SDK for [Savanto](https://savanto.ai) — AI-powered search, chat, recommendations, and knowledge base management.
+
+Auto-generated from the [Savanto OpenAPI spec](https://savanto.ai/docs/api). Every endpoint is fully typed with zero manual maintenance.
+
+## Installation
+
+```bash
+npm install @savantoai/ai-sdk
+```
+
+Requires **Node.js >= 18** (uses native `fetch`). Works in modern browsers with no polyfills.
+
+## Quick Start
+
+```typescript
+import { createClient, searchProducts, chat } from '@savantoai/ai-sdk';
+
+const client = createClient({
+  baseUrl: 'https://api.savanto.ai',
+  auth: 'if_sk_...',
+});
+
+// Search products
+const { data } = await searchProducts({
+  client,
+  body: { query: 'blue running shoes', limit: 10 },
+});
+console.log(data);
+
+// AI chat
+const { data: chatResponse } = await chat({
+  client,
+  body: { message: 'What shoes do you recommend?', threadId: 'thread-1' },
+});
+```
+
+## Authentication
+
+Pass your API key via the `auth` option on the client:
+
+```typescript
+const client = createClient({
+  baseUrl: 'https://api.savanto.ai',
+  auth: 'if_sk_...',
+});
+```
+
+The client automatically sends it as `Authorization: Bearer <key>` on every request.
+
+| Key Type | Prefix | Use |
+|----------|--------|-----|
+| **Secret** | `if_sk_` | Server-side only. Full access to all endpoints. |
+| **Publishable** | `if_pk_` | Safe for client-side. Limited to search, chat, feedback, and prompts. |
+
+## Examples
+
+### Products
+
+```typescript
+import {
+  searchProducts,
+  upsertProduct,
+  getProduct,
+  deleteProduct,
+  bulkUpsertProducts,
+  bulkDeleteProducts,
+  listProductIds,
+} from '@savantoai/ai-sdk';
+
+// Search
+const { data } = await searchProducts({
+  client,
+  body: { query: 'warm jacket', limit: 10 },
+});
+
+// Upsert
+await upsertProduct({
+  client,
+  body: { id: 'prod-1', name: 'Running Shoe', price: 99.99 },
+});
+
+// Get / Delete
+const { data: product } = await getProduct({ client, path: { id: 'prod-1' } });
+await deleteProduct({ client, path: { id: 'prod-1' } });
+
+// Bulk operations
+await bulkUpsertProducts({
+  client,
+  body: { items: [{ id: 'p1', name: 'Shoe' }, { id: 'p2', name: 'Boot' }] },
+});
+await bulkDeleteProducts({ client, body: { ids: ['p1', 'p2'] } });
+
+// List IDs
+const { data: ids } = await listProductIds({ client });
+```
+
+### Chat
+
+```typescript
+import { chat } from '@savantoai/ai-sdk';
+
+const { data, response } = await chat({
+  client,
+  body: {
+    message: 'What is your return policy?',
+    threadId: 'thread-1',
+    stream: true,
+  },
+});
+
+// For streaming (NDJSON), read the response body directly:
+const reader = response.body!.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  const lines = decoder.decode(value).split('\n').filter(Boolean);
+  for (const line of lines) {
+    const chunk = JSON.parse(line);
+    if (chunk.type === 'text_delta') process.stdout.write(chunk.data);
+  }
+}
+```
+
+### Posts
+
+Same pattern as products — `upsertPost`, `searchPosts`, `getPost`, `deletePost`, `bulkUpsertPosts`, `bulkDeletePosts`, `listPostIds`.
+
+```typescript
+import { searchPosts, upsertPost } from '@savantoai/ai-sdk';
+
+await upsertPost({
+  client,
+  body: { id: 'post-1', title: 'Return Policy', content: '...' },
+});
+
+const { data } = await searchPosts({
+  client,
+  body: { query: 'shipping policy' },
+});
+```
+
+### Feedback
+
+```typescript
+import { submitFeedback, listFeedback } from '@savantoai/ai-sdk';
+
+// Submit (publishable key safe)
+await submitFeedback({
+  client,
+  body: { threadId: 'thread-1', messageIndex: 0, rating: 5, comment: 'Helpful!' },
+});
+
+// List (secret key)
+const { data } = await listFeedback({ client });
+```
+
+### Threads
+
+```typescript
+import { searchThreads, getThreadMessages, deleteThread } from '@savantoai/ai-sdk';
+
+const { data } = await searchThreads({
+  client,
+  body: { query: 'returns' },
+});
+
+const { data: messages } = await getThreadMessages({ client, path: { id: 'thread-1' } });
+await deleteThread({ client, path: { id: 'thread-1' } });
+```
+
+### Webhooks
+
+```typescript
+import { createWebhook, listWebhooks, testWebhook } from '@savantoai/ai-sdk';
+
+await createWebhook({
+  client,
+  body: { name: 'Inventory sync', url: 'https://example.com/hook', events: ['product.upsert'] },
+});
+
+const { data } = await listWebhooks({ client });
+const { data: result } = await testWebhook({ client, path: { id: 'webhook-1' } });
+```
+
+### Recommendations
+
+```typescript
+import { getProductRecommendations } from '@savantoai/ai-sdk';
+
+const { data } = await getProductRecommendations({
+  client,
+  body: { productId: 'prod-1', maxRecommendations: 5 },
+});
+```
+
+### Crawl & Scrape
+
+```typescript
+import { startCrawl, getCrawlStatus, scrapePage } from '@savantoai/ai-sdk';
+
+await startCrawl({ client, body: { url: 'https://mystore.com' } });
+const { data } = await getCrawlStatus({ client, path: { id: 'crawl-abc' } });
+await scrapePage({ client, body: { url: 'https://mystore.com/about' } });
+```
+
+## Response Format
+
+Every function returns `{ data, error, response }`:
+
+```typescript
+const result = await searchProducts({ client, body: { query: 'shoes' } });
+
+if (result.error) {
+  // Typed error: { error: { message: string, code: string } }
+  console.error(result.error);
+} else {
+  console.log(result.data);
+}
+```
+
+To throw on errors instead of returning them:
+
+```typescript
+const { data } = await searchProducts({
+  client,
+  body: { query: 'shoes' },
+  throwOnError: true,
+});
+```
+
+## TypeScript
+
+All types are exported:
+
+```typescript
+import type {
+  Product,
+  ProductInput,
+  ProductSearchRequest,
+  Post,
+  ChatRequest,
+  ChatStreamChunk,
+  Taxonomy,
+  Prompt,
+  FeedbackSubmission,
+  ErrorResponse,
+} from '@savantoai/ai-sdk';
+```
+
+## Utilities
+
+```typescript
+import { workspaceIdFromUrl } from '@savantoai/ai-sdk';
+
+workspaceIdFromUrl('https://mystore.com');       // 'mystore-com'
+workspaceIdFromUrl('my-store.myshopify.com');     // 'my-store-myshopify-com'
+```
+
+## API Reference
+
+Full endpoint documentation with request/response schemas:
+
+**[savanto.ai/docs/api](https://savanto.ai/docs/api)**
+
+## Regeneration
+
+The SDK is auto-generated from the OpenAPI spec. To regenerate after API changes:
+
+```bash
+cd cloud && npm run openapi          # extract spec to cloud/openapi.json
+cd sdks/javascript && npm run generate  # regenerate src/generated/
+```
+
+## License
+
+MIT