@subscribeflow/sdk 1.0.25 → 1.0.26

package/README.md

@@ -1,43 +1,64 @@
+<p align="center">
+  <a href="https://subscribeflow.net">
+    <img src="https://docs.subscribeflow.net/assets/sdk-hero.svg" alt="SubscribeFlow" width="100%">
+  </a>
+</p>
+
 # @subscribeflow/sdk
 
-Official TypeScript SDK for the SubscribeFlow API.
+Official TypeScript SDK for SubscribeFlow — full type safety, tree-shakeable, zero dependencies. Manage email subscriptions, campaigns, and GDPR-compliant preference centers.
+
+[![npm Version](https://img.shields.io/npm/v/@subscribeflow/sdk)](https://www.npmjs.com/package/@subscribeflow/sdk)
+[![npm Downloads](https://img.shields.io/npm/dm/@subscribeflow/sdk)](https://www.npmjs.com/package/@subscribeflow/sdk)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://www.npmjs.com/package/@subscribeflow/sdk)
+[![License](https://img.shields.io/npm/l/@subscribeflow/sdk)](https://www.npmjs.com/package/@subscribeflow/sdk)
+[![Works with Claude](https://img.shields.io/badge/Works%20with-Claude-blueviolet)](https://docs.subscribeflow.net/sdk/mcp)
+
+[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)
+
+---
 
 ## Installation
 
-### Von GitHub (Empfohlen)
+### From npm (Recommended)
+
+Install the SDK using your preferred package manager:
 
 ```bash
 # npm
-npm install git+https://github.com/talent-factory/subscribe-flow.git#subdirectory=sdk/typescript
+npm install @subscribeflow/sdk
 
 # yarn
-yarn add git+https://github.com/talent-factory/subscribe-flow.git#subdirectory=sdk/typescript
+yarn add @subscribeflow/sdk
 
 # bun
-bun add github:talent-factory/subscribe-flow#subdirectory=sdk/typescript
+bun add @subscribeflow/sdk
 ```
 
-In `package.json`:
+Or add it directly to your `package.json`:
+
 ```json
 {
   "dependencies": {
-    "@subscribeflow/sdk": "git+https://github.com/talent-factory/subscribe-flow.git#subdirectory=sdk/typescript"
+    "@subscribeflow/sdk": "^1.0.0"
   }
 }
 ```
 
-### Lokale Entwicklung
+### Local Development
+
+If you are developing the SDK alongside your application, you can link it locally instead of installing from the registry.
 
-Für parallele Entwicklung von SDK und Anwendung gibt es mehrere Optionen:
+#### Option 1: `file:` Protocol (Simplest)
 
-#### Option 1: `file:` Protokoll (Einfachste)
+Point your dependency directly at the local SDK directory:
 
 ```bash
 # npm/yarn/pnpm
-npm install /pfad/zu/subscribeflow/sdk/typescript
+npm install /path/to/subscribeflow/sdk/typescript
 
 # bun
-bun add /pfad/zu/subscribeflow/sdk/typescript
+bun add /path/to/subscribeflow/sdk/typescript
 ```
 
 In `package.json`:
@@ -51,21 +72,23 @@ In `package.json`:
 
 #### Option 2: `npm link` / `bun link` (Symlink)
 
+Create a global symlink so changes to the SDK are reflected immediately without reinstalling:
+
 ```bash
-# Im SDK-Verzeichnis
-cd /pfad/zu/subscribeflow/sdk/typescript
-npm link  # oder: bun link
+# In the SDK directory
+cd /path/to/subscribeflow/sdk/typescript
+npm link  # or: bun link
 
-# In deinem Projekt
-cd /pfad/zu/deinem/projekt
-npm link @subscribeflow/sdk  # oder: bun link @subscribeflow/sdk
+# In your project
+cd /path/to/your/project
+npm link @subscribeflow/sdk  # or: bun link @subscribeflow/sdk
 ```
 
-**Vorteil:** Änderungen am SDK sind sofort verfügbar ohne Neuinstallation.
+**Advantage:** Any change you make to the SDK source is immediately available in your project without reinstalling.
 
 #### Option 3: Workspace (Monorepo)
 
-Für Projekte im selben Repository:
+For projects within the same repository, use workspaces:
 
 ```json
 // package.json (root)
@@ -74,14 +97,16 @@ Für Projekte im selben Repository:
 }
 ```
 
-### Best Practice für lokale Entwicklung
+### Best Practices for Local Development
 
-1. **Während der Entwicklung:** `npm link` oder `file:` verwenden
-2. **Vor dem Commit:** Auf GitHub-URL umstellen
-3. **CI/CD:** GitHub-URL nutzen
+1. **During development:** Use `npm link` or `file:` for fast iteration
+2. **Before committing:** Switch back to the npm registry version
+3. **CI/CD:** Always use the npm registry
 
 ## Quick Start
 
+The 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.
+
 ```typescript
 import { SubscribeFlowClient } from '@subscribeflow/sdk';
 
@@ -90,7 +115,7 @@ const client = new SubscribeFlowClient({
   baseUrl: 'https://api.subscribeflow.net', // optional, this is the default
 });
 
-// Create a subscriber
+// Create a subscriber with tags and metadata
 const subscriber = await client.subscribers.create({
   email: 'user@example.com',
   tags: ['newsletter', 'product-updates'],
@@ -104,51 +129,60 @@ console.log('Created subscriber:', subscriber.id);
 
 ### Subscribers
 
+Subscribers 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.
+
 ```typescript
-// List subscribers
+// List subscribers with optional filters
+// Returns paginated results with items, total count, and cursor for pagination
 const { items, total, cursor } = await client.subscribers.list({
   limit: 50,
   status: 'active',
 });
 
-// Get a subscriber
+// Get a single subscriber by ID
 const subscriber = await client.subscribers.get('subscriber-id');
 
-// Update a subscriber
+// Update subscriber metadata
+// Only the fields you pass will be changed; everything else stays the same
 const updated = await client.subscribers.update('subscriber-id', {
   metadata: { plan: 'premium' },
 });
 
-// Delete a subscriber
+// Permanently delete a subscriber and all associated data
 await client.subscribers.delete('subscriber-id');
 ```
 
 ### Tags
 
+Tags 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.
+
 ```typescript
-// Create a tag
+// Create a new tag with a human-readable name and a URL-safe slug
 const tag = await client.tags.create({
   name: 'Product Updates',
   slug: 'product-updates',
   description: 'Get notified about new features and improvements',
 });
 
-// List tags
+// List all tags in your organization
 const { items } = await client.tags.list();
 
-// Update a tag
+// Update a tag's description or other properties
 await client.tags.update('tag-id', {
   description: 'Updated description',
 });
 
-// Delete a tag
+// Delete a tag (subscribers will be automatically unsubscribed)
 await client.tags.delete('tag-id');
 ```
 
 ### Templates
 
+Templates define the content and layout of your emails. SubscribeFlow uses MJML for responsive email rendering and supports Mustache-style variables for dynamic content.
+
 ```typescript
-// Create an email template
+// Create a new email template with MJML content
+// Variables like {{company}} will be replaced when sending
 const template = await client.templates.create({
   name: 'Welcome Email',
   subject: 'Welcome to {{company}}!',
@@ -156,19 +190,19 @@ const template = await client.templates.create({
   category: 'transactional',
 });
 
-// List templates
+// List templates, optionally filtered by category
 const { items } = await client.templates.list({ category: 'transactional' });
 
-// Get a template by slug
+// Look up a template by its slug (useful for send operations)
 const tmpl = await client.templates.getBySlug('welcome-email');
 
-// Preview a template
+// Preview how a template will look with specific variable values
 const preview = await client.templates.preview('template-id', {
   company: 'Acme Inc',
 });
 console.log(preview.html);
 
-// Update a template
+// Update a template's subject or content
 await client.templates.update('template-id', { subject: 'New Subject' });
 
 // Delete a template
@@ -177,131 +211,143 @@ await client.templates.delete('template-id');
 
 ### Email Send
 
+Send 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.
+
 ```typescript
-// Send a transactional email
+// Send a transactional email to a single recipient
 const result = await client.emails.send({
   template_slug: 'welcome-email',
   to: 'user@example.com',
   variables: { company: 'Acme Inc' },
-  idempotency_key: 'unique-key-123',
+  idempotency_key: 'unique-key-123', // prevents duplicate sends on retry
 });
 console.log('Email queued:', result.id);
 ```
 
 ### Campaigns
 
+Campaigns 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.
+
 ```typescript
-// Create a campaign
+// Create a campaign draft targeting subscribers with specific tags
 const campaign = await client.campaigns.create({
   name: 'February Newsletter',
   template_id: 'template-uuid',
   tag_filter: { include_tags: ['newsletter'], match: 'any' },
 });
 
-// List campaigns
+// List campaigns filtered by status
 const campaigns = await client.campaigns.list({ status: 'draft' });
 
-// Preview recipient count
+// Preview how many subscribers will receive this campaign
 const count = await client.campaigns.countRecipients('campaign-id');
 console.log(`Will send to ${count.count} subscribers`);
 
-// Send the campaign
+// Send the campaign (moves from draft to sending)
 const sendResult = await client.campaigns.send('campaign-id');
 
-// Cancel a running campaign
+// Cancel a running campaign (emails already sent cannot be recalled)
 await client.campaigns.cancel('campaign-id');
 ```
 
 ### Email Triggers
 
+Triggers 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.
+
 ```typescript
-// Create an event-based trigger
+// Create a trigger that fires when a subscriber is created
 const trigger = await client.triggers.create({
   event_type: 'subscriber.created',
   template_id: 'welcome-template-uuid',
   description: 'Send welcome email on signup',
 });
 
-// List triggers
+// List all triggers
 const triggers = await client.triggers.list();
 
-// Update a trigger
+// Deactivate a trigger without deleting it
 await client.triggers.update('trigger-id', { is_active: false });
 
-// Delete a trigger
+// Permanently delete a trigger
 await client.triggers.delete('trigger-id');
 ```
 
 ### Webhooks
 
+Webhooks 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.
+
 ```typescript
-// Create a webhook endpoint
+// Register a new webhook endpoint for specific event types
 const webhook = await client.webhooks.create({
   url: 'https://your-app.com/webhooks/subscribeflow',
   events: ['subscriber.created', 'tag.subscribed'],
   description: 'Main webhook endpoint',
 });
 
-// The signing secret is only returned on creation
+// Important: the signing secret is only returned on creation — store it securely
 console.log('Signing secret:', webhook.signing_secret);
 
-// List webhook endpoints
+// List all registered webhook endpoints
 const { items } = await client.webhooks.list();
 
-// Update a webhook
+// Update the events a webhook listens to
 await client.webhooks.update('webhook-id', {
   events: ['subscriber.created', 'subscriber.deleted'],
 });
 
-// Test a webhook
+// Test a webhook by sending a sample payload to your endpoint
 const result = await client.webhooks.test('webhook-id', 'subscriber.created');
 if (result.success) {
   console.log('Webhook is working!');
 }
 
-// Rotate signing secret
+// Rotate the signing secret (invalidates the old one immediately)
 const rotated = await client.webhooks.rotateSecret('webhook-id');
 console.log('New secret:', rotated.signing_secret);
 
-// View delivery history
+// View delivery history to debug failed deliveries
 const deliveries = await client.webhooks.listDeliveries('webhook-id');
 
-// Get delivery statistics
+// Get aggregate delivery statistics
 const stats = await client.webhooks.getDeliveryStats('webhook-id');
 console.log(`Success rate: ${stats.success_rate}%`);
 
-// Retry a failed delivery
+// Retry a specific failed delivery
 await client.webhooks.retryDelivery('webhook-id', 'delivery-id');
 
-// Delete a webhook
+// Remove a webhook endpoint
 await client.webhooks.delete('webhook-id');
 ```
 
 ### Preference Center
 
+The 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).
+
 ```typescript
-// Generate a preference center token
+// Generate a time-limited preference center token for a subscriber
 const tokenResponse = await client.subscribers.generatePreferenceToken('subscriber-id');
 
-// Access the preference center with the token
+// Create a preference center client using the token
 const prefCenter = client.preferenceCenter(tokenResponse.token);
 
-// Get subscriber preferences and available tags
+// Retrieve the subscriber's current preferences and all available tags
 const info = await prefCenter.getInfo();
 
-// Subscribe/unsubscribe from tags
+// Subscribe or unsubscribe from individual tags
 await prefCenter.subscribeTag('tag-id');
 await prefCenter.unsubscribeTag('tag-id');
 
-// Export all data (DSGVO)
+// Export all subscriber data as JSON (GDPR Art. 20 — Right to Data Portability)
 const exportData = await prefCenter.exportData();
 
-// Delete account (DSGVO)
+// Permanently delete the subscriber account (GDPR Art. 17 — Right to Erasure)
 await prefCenter.deleteAccount();
 ```
 
 ## Error Handling
 
+All API errors are thrown as `SubscribeFlowError` instances with structured error details. You can use `instanceof` checks to handle specific error types.
+
 ```typescript
 import { SubscribeFlowClient, SubscribeFlowError } from '@subscribeflow/sdk';
 
@@ -310,18 +356,20 @@ try {
 } catch (error) {
   if (error instanceof SubscribeFlowError) {
     console.error('API Error:', error.message);
-    console.error('Status:', error.status);
-    console.error('Type:', error.type);
-    console.error('Detail:', error.detail);
+    console.error('Status:', error.status);   // HTTP status code (e.g. 404)
+    console.error('Type:', error.type);       // Machine-readable error type
+    console.error('Detail:', error.detail);   // Human-readable description
   }
 }
 ```
 
 ## Configuration
 
+The client accepts configuration options when initialized. Only the `apiKey` is required.
+
 ```typescript
 const client = new SubscribeFlowClient({
-  // Required: Your API key
+  // Required: Your API key (starts with sf_live_ or sf_test_)
   apiKey: 'sf_live_xxx',
 
   // Optional: API base URL (default: https://api.subscribeflow.net)
@@ -329,9 +377,9 @@ const client = new SubscribeFlowClient({
 });
 ```
 
-### Lokale API-Instanz
+### Local API Instance
 
-Für Entwicklung gegen eine lokale SubscribeFlow-Instanz:
+When developing against a local SubscribeFlow backend, point the client to your local server:
 
 ```typescript
 const client = new SubscribeFlowClient({
@@ -342,22 +390,22 @@ const client = new SubscribeFlowClient({
 
 ## TypeScript Support
 
-This SDK is written in TypeScript and provides full type definitions out of the box.
+This 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.
 
 ```typescript
 import type { paths, components } from '@subscribeflow/sdk';
 
-// Use component schemas
+// Use component schemas for your own types
 type Subscriber = components['schemas']['SubscriberResponse'];
 type Tag = components['schemas']['TagResponse'];
 
-// Type-safe API operations
+// All API operations are fully type-safe
 const subscriber: Subscriber = await client.subscribers.get('id');
 ```
 
 ## Regenerating Types
 
-If the API changes, you can regenerate the TypeScript types:
+If the API changes, you can regenerate the TypeScript types from the OpenAPI schema:
 
 ```bash
 # Make sure the backend is running
@@ -368,11 +416,19 @@ curl http://localhost:8000/openapi.json -o openapi.json
 bunx openapi-typescript openapi.json -o src/api-types.ts
 ```
 
+## MCP Server (Claude Integration)
+
+The 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.
+
+See the [MCP Integration Guide](https://docs.subscribeflow.net/sdk/mcp) for setup instructions.
+
 ## Links
 
-- [API Documentation](https://docs.subscribeflow.net/reference/api)
-- [Getting Started Guide](https://docs.subscribeflow.net/getting-started)
-- [Webhook Integration](https://docs.subscribeflow.net/guides/webhooks)
+- [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)
+- [Feedback](https://subscribeflow.net/feedback)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@subscribeflow/sdk",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "description": "TypeScript SDK for SubscribeFlow API - Email subscription management",
   "author": "SubscribeFlow Team",
   "license": "MIT",