@subscribeflow/sdk 1.0.30 → 1.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@subscribeflow/sdk",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "TypeScript SDK for SubscribeFlow API - Email subscription management",
   "author": "SubscribeFlow Team",
   "license": "MIT",
@@ -58,5 +58,7 @@
   },
   "publishConfig": {
     "access": "public"
-  }
-}
+  },
+  "readme": "# @subscribeflow/sdk\n\n<p align=\"center\">\n  <a href=\"https://subscribeflow.net\">\n    <img src=\"https://docs.subscribeflow.net/assets/sdk-hero.svg\" alt=\"SubscribeFlow\" width=\"100%\">\n  </a>\n</p>\n\nOfficial TypeScript SDK for SubscribeFlow — full type safety, tree-shakeable, zero dependencies. Manage email subscriptions, campaigns, and GDPR-compliant preference centers.\n\n[![npm Version](https://img.shields.io/npm/v/@subscribeflow/sdk)](https://www.npmjs.com/package/@subscribeflow/sdk)\n[![npm Downloads](https://img.shields.io/npm/dm/@subscribeflow/sdk)](https://www.npmjs.com/package/@subscribeflow/sdk)\n[![Node Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://www.npmjs.com/package/@subscribeflow/sdk)\n[![License](https://img.shields.io/npm/l/@subscribeflow/sdk)](https://www.npmjs.com/package/@subscribeflow/sdk)\n[![Works with Claude](https://img.shields.io/badge/Works%20with-Claude-blueviolet)](https://docs.subscribeflow.net/sdk/mcp)\n\n[Dashboard](https://subscribeflow.net) | [Documentation](https://docs.subscribeflow.net) | [API Reference](https://docs.subscribeflow.net/api/reference) | [MCP Integration](https://docs.subscribeflow.net/sdk/mcp)\n\n---\n\n## Installation\n\n### From npm (Recommended)\n\nInstall the SDK using your preferred package manager:\n\n```bash\n# npm\nnpm install @subscribeflow/sdk\n\n# yarn\nyarn add @subscribeflow/sdk\n\n# bun\nbun add @subscribeflow/sdk\n```\n\nOr add it directly to your `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@subscribeflow/sdk\": \"^1.0.0\"\n  }\n}\n```\n\n### Local Development\n\nIf you are developing the SDK alongside your application, you can link it locally instead of installing from the registry.\n\n#### Option 1: `file:` Protocol (Simplest)\n\nPoint your dependency directly at the local SDK directory:\n\n```bash\n# npm/yarn/pnpm\nnpm install /path/to/subscribeflow/sdk/typescript\n\n# bun\nbun add /path/to/subscribeflow/sdk/typescript\n```\n\nIn `package.json`:\n```json\n{\n  \"dependencies\": {\n    \"@subscribeflow/sdk\": \"file:../subscribeflow/sdk/typescript\"\n  }\n}\n```\n\n#### Option 2: `npm link` / `bun link` (Symlink)\n\nCreate a global symlink so changes to the SDK are reflected immediately without reinstalling:\n\n```bash\n# In the SDK directory\ncd /path/to/subscribeflow/sdk/typescript\nnpm link  # or: bun link\n\n# In your project\ncd /path/to/your/project\nnpm link @subscribeflow/sdk  # or: bun link @subscribeflow/sdk\n```\n\n**Advantage:** Any change you make to the SDK source is immediately available in your project without reinstalling.\n\n#### Option 3: Workspace (Monorepo)\n\nFor projects within the same repository, use workspaces:\n\n```json\n// package.json (root)\n{\n  \"workspaces\": [\"apps/*\", \"sdk/*\"]\n}\n```\n\n### Best Practices for Local Development\n\n1. **During development:** Use `npm link` or `file:` for fast iteration\n2. **Before committing:** Switch back to the npm registry version\n3. **CI/CD:** Always use the npm registry\n\n## Quick Start\n\nThe following example shows how to initialize the client and create your first subscriber. You need an API key, which you can generate from your SubscribeFlow admin dashboard.\n\n```typescript\nimport { SubscribeFlowClient } from '@subscribeflow/sdk';\n\nconst client = new SubscribeFlowClient({\n  apiKey: process.env.SUBSCRIBEFLOW_API_KEY!,\n  baseUrl: 'https://api.subscribeflow.net', // optional, this is the default\n});\n\n// Create a subscriber with tags and metadata\nconst subscriber = await client.subscribers.create({\n  email: 'user@example.com',\n  tags: ['newsletter', 'product-updates'],\n  metadata: { source: 'website' },\n});\n\nconsole.log('Created subscriber:', subscriber.id);\n```\n\n## Usage\n\n### Subscribers\n\nSubscribers are the core entity in SubscribeFlow. Each subscriber represents a person identified by their email address. You can list, create, update, and delete subscribers, as well as manage their tag subscriptions and metadata.\n\n```typescript\n// List subscribers with optional filters\n// Returns paginated results with items, total count, and cursor for pagination\nconst { items, total, cursor } = await client.subscribers.list({\n  limit: 50,\n  status: 'active',\n});\n\n// Get a single subscriber by ID\nconst subscriber = await client.subscribers.get('subscriber-id');\n\n// Update subscriber metadata\n// Only the fields you pass will be changed; everything else stays the same\nconst updated = await client.subscribers.update('subscriber-id', {\n  metadata: { plan: 'premium' },\n});\n\n// Permanently delete a subscriber and all associated data\nawait client.subscribers.delete('subscriber-id');\n```\n\n### Tags\n\nTags represent topics or categories that subscribers can opt into. They are the building block of SubscribeFlow's granular preference management. Unlike traditional mailing lists, subscribers can actively discover and subscribe to tags they are interested in.\n\n```typescript\n// Create a new tag with a human-readable name and a URL-safe slug\nconst tag = await client.tags.create({\n  name: 'Product Updates',\n  slug: 'product-updates',\n  description: 'Get notified about new features and improvements',\n});\n\n// List all tags in your organization\nconst { items } = await client.tags.list();\n\n// Update a tag's description or other properties\nawait client.tags.update('tag-id', {\n  description: 'Updated description',\n});\n\n// Delete a tag (subscribers will be automatically unsubscribed)\nawait client.tags.delete('tag-id');\n```\n\n### Templates\n\nTemplates define the content and layout of your emails. SubscribeFlow uses MJML for responsive email rendering and supports Mustache-style variables for dynamic content.\n\n```typescript\n// Create a new email template with MJML content\n// Variables like {{company}} will be replaced when sending\nconst template = await client.templates.create({\n  name: 'Welcome Email',\n  subject: 'Welcome to {{company}}!',\n  mjml_content: '<mjml><mj-body>...</mj-body></mjml>',\n  category: 'transactional',\n});\n\n// List templates, optionally filtered by category\nconst { items } = await client.templates.list({ category: 'transactional' });\n\n// Look up a template by its slug (useful for send operations)\nconst tmpl = await client.templates.getBySlug('welcome-email');\n\n// Preview how a template will look with specific variable values\nconst preview = await client.templates.preview('template-id', {\n  company: 'Acme Inc',\n});\nconsole.log(preview.html);\n\n// Update a template's subject or content\nawait client.templates.update('template-id', { subject: 'New Subject' });\n\n// Delete a template\nawait client.templates.delete('template-id');\n```\n\n### Email Send\n\nSend individual transactional emails using a template. Each send requires a template slug and recipient. The optional `idempotency_key` prevents duplicate sends if the same request is retried.\n\n```typescript\n// Send a transactional email to a single recipient\nconst result = await client.emails.send({\n  template_slug: 'welcome-email',\n  to: 'user@example.com',\n  variables: { company: 'Acme Inc' },\n  idempotency_key: 'unique-key-123', // prevents duplicate sends on retry\n});\nconsole.log('Email queued:', result.id);\n```\n\n### Campaigns\n\nCampaigns let you send emails to groups of subscribers based on tag filters. Create a draft, preview the recipient count, and then send it. Running campaigns can be cancelled.\n\n```typescript\n// Create a campaign draft targeting subscribers with specific tags\nconst campaign = await client.campaigns.create({\n  name: 'February Newsletter',\n  template_id: 'template-uuid',\n  tag_filter: { include_tags: ['newsletter'], match: 'any' },\n});\n\n// List campaigns filtered by status\nconst campaigns = await client.campaigns.list({ status: 'draft' });\n\n// Preview how many subscribers will receive this campaign\nconst count = await client.campaigns.countRecipients('campaign-id');\nconsole.log(`Will send to ${count.count} subscribers`);\n\n// Send the campaign (moves from draft to sending)\nconst sendResult = await client.campaigns.send('campaign-id');\n\n// Cancel a running campaign (emails already sent cannot be recalled)\nawait client.campaigns.cancel('campaign-id');\n```\n\n### Email Triggers\n\nTriggers automatically send emails in response to events. For example, you can send a welcome email whenever a new subscriber is created. Triggers can be activated or deactivated without deleting them.\n\n```typescript\n// Create a trigger that fires when a subscriber is created\nconst trigger = await client.triggers.create({\n  event_type: 'subscriber.created',\n  template_id: 'welcome-template-uuid',\n  description: 'Send welcome email on signup',\n});\n\n// List all triggers\nconst triggers = await client.triggers.list();\n\n// Deactivate a trigger without deleting it\nawait client.triggers.update('trigger-id', { is_active: false });\n\n// Permanently delete a trigger\nawait client.triggers.delete('trigger-id');\n```\n\n### Webhooks\n\nWebhooks let your application receive real-time notifications when events occur in SubscribeFlow. Each webhook endpoint receives signed HTTP POST requests that you can verify using the signing secret.\n\n```typescript\n// Register a new webhook endpoint for specific event types\nconst webhook = await client.webhooks.create({\n  url: 'https://your-app.com/webhooks/subscribeflow',\n  events: ['subscriber.created', 'tag.subscribed'],\n  description: 'Main webhook endpoint',\n});\n\n// Important: the signing secret is only returned on creation — store it securely\nconsole.log('Signing secret:', webhook.signing_secret);\n\n// List all registered webhook endpoints\nconst { items } = await client.webhooks.list();\n\n// Update the events a webhook listens to\nawait client.webhooks.update('webhook-id', {\n  events: ['subscriber.created', 'subscriber.deleted'],\n});\n\n// Test a webhook by sending a sample payload to your endpoint\nconst result = await client.webhooks.test('webhook-id', 'subscriber.created');\nif (result.success) {\n  console.log('Webhook is working!');\n}\n\n// Rotate the signing secret (invalidates the old one immediately)\nconst rotated = await client.webhooks.rotateSecret('webhook-id');\nconsole.log('New secret:', rotated.signing_secret);\n\n// View delivery history to debug failed deliveries\nconst deliveries = await client.webhooks.listDeliveries('webhook-id');\n\n// Get aggregate delivery statistics\nconst stats = await client.webhooks.getDeliveryStats('webhook-id');\nconsole.log(`Success rate: ${stats.success_rate}%`);\n\n// Retry a specific failed delivery\nawait client.webhooks.retryDelivery('webhook-id', 'delivery-id');\n\n// Remove a webhook endpoint\nawait client.webhooks.delete('webhook-id');\n```\n\n### Preference Center\n\nThe Preference Center allows subscribers to manage their own email preferences. Generate a secure token for a subscriber, then use it to access their preferences. This powers the self-service UI where subscribers can subscribe to new tags, unsubscribe, export their data, or delete their account (GDPR compliance).\n\n```typescript\n// Generate a time-limited preference center token for a subscriber\nconst tokenResponse = await client.subscribers.generatePreferenceToken('subscriber-id');\n\n// Create a preference center client using the token\nconst prefCenter = client.preferenceCenter(tokenResponse.token);\n\n// Retrieve the subscriber's current preferences and all available tags\nconst info = await prefCenter.getInfo();\n\n// Subscribe or unsubscribe from individual tags\nawait prefCenter.subscribeTag('tag-id');\nawait prefCenter.unsubscribeTag('tag-id');\n\n// Export all subscriber data as JSON (GDPR Art. 20 — Right to Data Portability)\nconst exportData = await prefCenter.exportData();\n\n// Permanently delete the subscriber account (GDPR Art. 17 — Right to Erasure)\nawait prefCenter.deleteAccount();\n```\n\n## Error Handling\n\nAll API errors are thrown as `SubscribeFlowError` instances with structured error details. You can use `instanceof` checks to handle specific error types.\n\n```typescript\nimport { SubscribeFlowClient, SubscribeFlowError } from '@subscribeflow/sdk';\n\ntry {\n  await client.subscribers.get('non-existent-id');\n} catch (error) {\n  if (error instanceof SubscribeFlowError) {\n    console.error('API Error:', error.message);\n    console.error('Status:', error.status);   // HTTP status code (e.g. 404)\n    console.error('Type:', error.type);       // Machine-readable error type\n    console.error('Detail:', error.detail);   // Human-readable description\n  }\n}\n```\n\n## Configuration\n\nThe client accepts configuration options when initialized. Only the `apiKey` is required.\n\n```typescript\nconst client = new SubscribeFlowClient({\n  // Required: Your API key (starts with sf_live_ or sf_test_)\n  apiKey: 'sf_live_xxx',\n\n  // Optional: API base URL (default: https://api.subscribeflow.net)\n  baseUrl: 'https://api.subscribeflow.net',\n});\n```\n\n### Local API Instance\n\nWhen developing against a local SubscribeFlow backend, point the client to your local server:\n\n```typescript\nconst client = new SubscribeFlowClient({\n  apiKey: 'sf_dev_xxx',\n  baseUrl: 'http://localhost:8000',\n});\n```\n\n## TypeScript Support\n\nThis SDK is written in TypeScript and provides full type definitions out of the box. You can import component schemas directly for use in your own type declarations.\n\n```typescript\nimport type { paths, components } from '@subscribeflow/sdk';\n\n// Use component schemas for your own types\ntype Subscriber = components['schemas']['SubscriberResponse'];\ntype Tag = components['schemas']['TagResponse'];\n\n// All API operations are fully type-safe\nconst subscriber: Subscriber = await client.subscribers.get('id');\n```\n\n## Regenerating Types\n\nIf the API changes, you can regenerate the TypeScript types from the OpenAPI schema:\n\n```bash\n# Make sure the backend is running\nmake backend\n\n# Fetch OpenAPI schema and generate types\ncurl http://localhost:8000/openapi.json -o openapi.json\nbunx openapi-typescript openapi.json -o src/api-types.ts\n```\n\n## MCP Server (Claude Integration)\n\nThe MCP server for Claude Desktop and Claude Code is available via the Python SDK. Install `subscribeflow[mcp]` to use natural-language commands with your SubscribeFlow account.\n\nSee the [MCP Integration Guide](https://docs.subscribeflow.net/sdk/mcp) for setup instructions.\n\n## Links\n\n- [Dashboard](https://subscribeflow.net)\n- [Documentation](https://docs.subscribeflow.net)\n- [API Reference](https://docs.subscribeflow.net/api/reference)\n- [MCP Integration](https://docs.subscribeflow.net/sdk/mcp)\n- [Feedback](https://subscribeflow.net/feedback)\n\n## License\n\nMIT\n",
+  "readmeFilename": "README.md"
+}