listbee 0.3.0

package/README.md

@@ -0,0 +1,552 @@
+# listbee
+
+Official TypeScript SDK for the [ListBee API](https://listbee.so) — one API call to sell and deliver digital content.
+
+## Install
+
+```bash
+npm install listbee
+```
+
+```bash
+pnpm add listbee
+```
+
+## Quick start
+
+```typescript
+import { ListBee } from 'listbee';
+
+const client = new ListBee({ apiKey: 'lb_...' });
+
+const listing = await client.listings.create({
+  name: 'SEO Playbook',
+  price: 2900,
+  content: 'https://example.com/seo-playbook.pdf',
+});
+console.log(listing.url); // https://buy.listbee.so/r7kq2xy9
+```
+
+Using an environment variable instead:
+
+```bash
+export LISTBEE_API_KEY="lb_..."
+```
+
+```typescript
+import { ListBee } from 'listbee';
+
+const client = new ListBee(); // reads LISTBEE_API_KEY automatically
+
+const listing = await client.listings.create({
+  name: 'SEO Playbook',
+  price: 2900,
+  content: 'https://example.com/seo-playbook.pdf',
+});
+console.log(listing.url);
+```
+
+## Authentication
+
+Pass your API key explicitly or via the `LISTBEE_API_KEY` environment variable.
+
+```typescript
+import { ListBee } from 'listbee';
+
+// Explicit key
+const client = new ListBee({ apiKey: 'lb_...' });
+
+// Environment variable (LISTBEE_API_KEY)
+const client = new ListBee();
+
+// process.env lookup
+const client = new ListBee({ apiKey: process.env.LISTBEE_API_KEY });
+```
+
+The key is validated lazily — the client constructs successfully even with a missing or invalid key. An `AuthenticationError` is raised only when you make the first API call.
+
+API keys start with `lb_`. Get yours at [listbee.so](https://listbee.so).
+
+## Resources
+
+### Listings
+
+```typescript
+import { ListBee } from 'listbee';
+
+const client = new ListBee({ apiKey: 'lb_...' });
+
+// Create — minimal
+const listing = await client.listings.create({
+  name: 'SEO Playbook',
+  price: 2900,       // $29.00 in cents
+  content: 'https://example.com/seo-playbook.pdf', // file URL, redirect URL, or plain text
+});
+
+// Create — all optional params
+const listing = await client.listings.create({
+  name: 'SEO Playbook 2026',
+  price: 2900,
+  content: 'https://example.com/seo-playbook.pdf',
+  description: 'A comprehensive guide to modern SEO techniques.',
+  tagline: 'Updated for 2026 algorithm changes',
+  highlights: ['50+ pages', 'Actionable tips', 'Free updates'],
+  cta: 'Get Instant Access',          // buy button text; defaults to "Buy Now"
+  cover_url: 'https://example.com/cover.png',
+  compare_at_price: 3900,             // strikethrough price
+  badges: ['Limited time', 'Best seller'],
+  cover_blur: 'auto',                 // "auto" | "true" | "false"
+  rating: 4.8,
+  rating_count: 1243,
+  reviews: [
+    { name: 'Clara D.', rating: 5.0, content: 'Excellent quality content.' },
+  ],
+  faqs: [
+    { q: 'Is this for beginners?', a: 'Yes, completely beginner-friendly.' },
+  ],
+  metadata: { source: 'n8n', campaign: 'launch-week' },
+});
+console.log(listing.id);  // lst_r7kq2xy9m3pR5tW1
+console.log(listing.url); // https://buy.listbee.so/m3pr5tw1
+
+// Get by slug
+const listing = await client.listings.get('m3pr5tw1');
+
+// List — paginated
+const page = await client.listings.list({ limit: 20 });
+for (const listing of page.data) {
+  console.log(listing.slug, listing.name);
+}
+
+// Update — partial updates
+const updated = await client.listings.update('r7kq2xy9', {
+  name: 'SEO Playbook 2026 Updated',
+  price: 3900,
+});
+
+// Pause / Resume
+await client.listings.pause('r7kq2xy9');
+await client.listings.resume('r7kq2xy9');
+
+// Delete
+await client.listings.delete('m3pr5tw1');
+```
+
+### Orders
+
+```typescript
+// List all orders
+const page = await client.orders.list();
+for (const order of page.data) {
+  console.log(order.id, order.status);
+}
+
+// Filter by status, listing, date range
+const page = await client.orders.list({
+  status: 'completed',
+  listing: 'seo-playbook',
+  created_after: new Date('2026-03-01'),
+  created_before: '2026-03-31T23:59:59Z', // Date objects or ISO strings
+});
+
+// Get by ID
+const order = await client.orders.get('ord_9xM4kP7nR2qT5wY1');
+console.log(order.listing_id, order.amount);
+```
+
+### Webhooks
+
+```typescript
+import { ListBee, WebhookEventType } from 'listbee';
+
+const client = new ListBee({ apiKey: 'lb_...' });
+
+// Create — subscribe to specific events
+const webhook = await client.webhooks.create({
+  name: 'Production endpoint',
+  url: 'https://example.com/webhooks/listbee',
+  events: [
+    WebhookEventType.ORDER_COMPLETED,
+    WebhookEventType.ORDER_REFUNDED,
+  ],
+});
+console.log(webhook.id);     // wh_3mK8nP2qR5tW7xY1
+console.log(webhook.secret); // HMAC signing key
+
+// Create — receive all events (omit events param)
+const webhook = await client.webhooks.create({
+  name: 'Catch-all',
+  url: 'https://example.com/webhooks/listbee-all',
+});
+
+// List
+const webhooks = await client.webhooks.list();
+for (const wh of webhooks) {
+  console.log(wh.id, wh.name, wh.enabled);
+}
+
+// Update — disable without deleting
+await client.webhooks.update('wh_3mK8nP2qR5tW7xY1', { enabled: false });
+
+// Update — change URL and events
+await client.webhooks.update('wh_3mK8nP2qR5tW7xY1', {
+  url: 'https://example.com/webhooks/v2',
+  events: [WebhookEventType.ORDER_COMPLETED],
+});
+
+// List delivery events
+const events = await client.webhooks.listEvents('wh_3mK8nP2qR5tW7xY1', {
+  status: 'failed',
+});
+for (const evt of events.data) {
+  console.log(evt.event_type, evt.status, evt.last_error);
+}
+
+// Test endpoint
+const test = await client.webhooks.test('wh_3mK8nP2qR5tW7xY1');
+console.log(test.success, test.status_code);
+
+// Delete
+await client.webhooks.delete('wh_3mK8nP2qR5tW7xY1');
+```
+
+### Account
+
+```typescript
+const account = await client.account.get();
+console.log(account.id);    // acc_7kQ2xY9mN3pR5tW1
+console.log(account.email); // seller@example.com
+console.log(account.plan);  // free | growth | scale
+console.log(account.readiness.operational);
+
+// Update Google Analytics tracking
+await client.account.update({ ga_measurement_id: 'G-XXXXXXXXXX' });
+
+// Clear GA tracking
+await client.account.update({ ga_measurement_id: null });
+```
+
+### Signup
+
+Agent self-service onboarding — no API key required:
+
+```typescript
+import { ListBee } from 'listbee';
+
+const client = new ListBee(); // no API key needed
+
+// Request a signup code
+await client.signup.create({ email: 'seller@example.com' });
+
+// Verify the code — returns account + API key
+const result = await client.signup.verify({
+  email: 'seller@example.com',
+  code: '123456',
+});
+console.log(result.api_key); // lb_... (one-time display)
+```
+
+### API keys
+
+```typescript
+// List all API keys
+const keys = await client.apiKeys.list();
+for (const key of keys) {
+  console.log(key.id, key.name);
+}
+
+// Create a new key — the key value is only shown once
+const newKey = await client.apiKeys.create({ name: 'CI pipeline' });
+console.log(newKey.key); // lb_... (save this immediately)
+
+// Delete a key
+await client.apiKeys.delete('lbk_7kQ2xY9mN3pR5tW1');
+```
+
+### Stores
+
+```typescript
+// Create a store
+const store = await client.stores.create({ handle: 'fitness-brand', name: 'Fitness Brand' });
+console.log(store.id);     // str_7kQ2xY9mN3pR5tW1vB8a
+console.log(store.handle); // fitness-brand
+
+// List all stores
+const stores = await client.stores.list();
+for (const s of stores.data) {
+  console.log(s.handle, s.display_name);
+}
+
+// Get a store
+const store = await client.stores.get('str_7kQ2xY9mN3pR5tW1vB8a');
+
+// Update a store
+const updated = await client.stores.update('str_7kQ2xY9mN3pR5tW1vB8a', {
+  name: 'Fitness Pro',
+  bio: 'Premium fitness content',
+  social_links: ['https://twitter.com/fitnesspro'],
+});
+
+// Delete a store
+await client.stores.delete('str_7kQ2xY9mN3pR5tW1vB8a');
+
+// Connect Stripe — returns a URL to redirect the user to
+const session = await client.stores.connectStripe('str_7kQ2xY9mN3pR5tW1vB8a');
+console.log(session.url); // redirect seller here
+
+// Custom domains
+const domain = await client.stores.setDomain('str_7kQ2xY9mN3pR5tW1vB8a', { domain: 'fitness.com' });
+console.log(domain.cname_target); // buy.listbee.so — point your CNAME here
+
+const verified = await client.stores.verifyDomain('str_7kQ2xY9mN3pR5tW1vB8a');
+console.log(verified.status); // "verified" or "pending"
+
+await client.stores.removeDomain('str_7kQ2xY9mN3pR5tW1vB8a');
+
+// Create a listing in a specific store
+const listing = await client.listings.create({
+  name: 'SEO Playbook',
+  price: 2900,
+  content: 'https://example.com/seo-playbook.pdf',
+  store_id: 'str_7kQ2xY9mN3pR5tW1vB8a',
+});
+```
+
+### Stripe
+
+```typescript
+// Set your Stripe secret key
+await client.stripe.setKey({ secretKey: 'sk_live_...' });
+
+// Generate a Stripe Connect onboarding link
+const connect = await client.stripe.connect();
+console.log(connect.url); // redirect seller here
+
+// Disconnect Stripe
+await client.stripe.disconnect();
+```
+
+## Readiness system
+
+Every listing and account includes a `readiness` field that tells you whether it can currently accept payments.
+
+- `listing.readiness.sellable` — `true` when buyers can complete a purchase
+- `account.readiness.operational` — `true` when the account can sell
+
+When `false`, an `actions` array explains what's needed and how to resolve each item. The `next` field points to the highest-priority action (prefers `kind: api`).
+
+```typescript
+import { ActionKind } from 'listbee';
+
+const account = await client.account.get();
+if (!account.readiness.operational) {
+  for (const action of account.readiness.actions) {
+    if (action.kind === ActionKind.API) {
+      console.log(`API action: ${action.code} -> ${action.resolve.endpoint}`);
+    } else {
+      console.log(`Manual step: ${action.code} -> ${action.resolve.url}`);
+    }
+  }
+  console.log(`Next action: ${account.readiness.next}`);
+}
+```
+
+## Pagination
+
+`listings.list()` and `orders.list()` return a `CursorPage` with cursor-based pagination.
+
+```typescript
+// First page
+const page = await client.listings.list({ limit: 10 });
+console.log(page.data);     // ListingResponse[]
+console.log(page.has_more); // true if more pages exist
+console.log(page.cursor);   // cursor string for the next page
+
+// Fetch next page
+if (page.has_more) {
+  const nextPage = await client.listings.list({ limit: 10, cursor: page.cursor });
+  console.log(nextPage.data);
+}
+```
+
+## Error handling
+
+```
+ListBeeError
+├── APIConnectionError   // network error — request never reached the server
+├── APITimeoutError      // request timed out
+└── APIStatusError       // server returned 4xx/5xx
+    ├── AuthenticationError    // 401 — invalid or missing API key
+    ├── NotFoundError          // 404 — resource not found
+    ├── ConflictError          // 409 — resource conflict
+    ├── ValidationError        // 422 — request validation failed
+    ├── RateLimitError         // 429 — rate limit exceeded
+    └── InternalServerError    // 500+ — server-side error
+```
+
+Catch specific errors:
+
+```typescript
+import {
+  ListBee,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError,
+  APIConnectionError,
+  APITimeoutError,
+  APIStatusError,
+} from 'listbee';
+
+const client = new ListBee({ apiKey: 'lb_...' });
+
+try {
+  const listing = await client.listings.get('does-not-exist');
+} catch (e) {
+  if (e instanceof NotFoundError) {
+    console.log(e.status); // 404
+    console.log(e.code);   // machine-readable code
+    console.log(e.detail); // human-readable explanation
+  } else if (e instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (e instanceof RateLimitError) {
+    console.log(`Rate limited. Resets at ${e.reset}, ${e.remaining}/${e.limit} remaining`);
+  } else if (e instanceof ValidationError) {
+    console.log(`Bad request — field: ${e.param}, detail: ${e.detail}`);
+  } else if (e instanceof APIConnectionError) {
+    console.log('Network error — check your connection');
+  } else if (e instanceof APITimeoutError) {
+    console.log('Request timed out');
+  } else if (e instanceof APIStatusError) {
+    console.log(`API error ${e.status}: ${e.detail}`);
+  }
+}
+```
+
+Error responses follow [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (Problem Details). All `APIStatusError` subclasses expose:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `status` | `number` | HTTP status code |
+| `code` | `string` | Machine-readable error code |
+| `detail` | `string` | Specific explanation |
+| `title` | `string` | Short, stable error category label |
+| `type` | `string` | URI identifying the error type |
+| `param` | `string \| null` | Request field that caused the error |
+
+`RateLimitError` additionally exposes `limit`, `remaining`, and `reset` (parsed from response headers).
+
+## Configuration
+
+```typescript
+import { ListBee } from 'listbee';
+
+const client = new ListBee({
+  apiKey: 'lb_...',
+  timeoutMs: 60_000,    // default: 30000
+  maxRetries: 5,        // default: 3; retries on 429/500/502/503/504
+  baseUrl: 'https://api.listbee.so', // default; override for testing
+});
+```
+
+`listings.create()` uses a default timeout of **120 seconds** because cover image processing can take longer. Pass `timeoutMs` to override:
+
+```typescript
+const listing = await client.listings.create({
+  name: 'Quick listing',
+  price: 999,
+  content: 'https://example.com/file.pdf',
+  timeoutMs: 30_000, // override the 120s default for this call
+});
+```
+
+## Types and enums
+
+All types are importable directly from `listbee`:
+
+```typescript
+import {
+  // Client
+  ListBee,
+  CursorPage,
+
+  // Response types
+  type ListingResponse,
+  type OrderResponse,
+  type WebhookResponse,
+  type AccountResponse,
+  type ApiKeyResponse,
+  type SignupResponse,
+  type VerifyResponse,
+  type StripeConnectSessionResponse,
+  type StoreResponse,
+  type StoreListResponse,
+  type DomainResponse,
+  type WebhookEventResponse,
+  type WebhookTestResponse,
+
+  // Enums (runtime values)
+  ContentType,        // "file" | "url" | "text"
+  OrderStatus,        // "completed"
+  WebhookEventType,   // "order.completed" | "order.refunded" | ...
+  ActionCode,         // "set_stripe_key" | "connect_stripe" | ...
+  ActionKind,         // "api" | "human"
+
+  // Errors
+  ListBeeError,
+  APIStatusError,
+  APIConnectionError,
+  APITimeoutError,
+  AuthenticationError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  RateLimitError,
+  InternalServerError,
+} from 'listbee';
+```
+
+Enums are `as const` objects — use them to avoid magic strings:
+
+```typescript
+import { ContentType, WebhookEventType } from 'listbee';
+
+// Check content type
+if (listing.content_type === ContentType.FILE) {
+  console.log('Delivers a file');
+}
+
+// Subscribe to specific events
+const webhook = await client.webhooks.create({
+  name: 'Orders only',
+  url: 'https://example.com/hooks',
+  events: [
+    WebhookEventType.ORDER_COMPLETED,
+    WebhookEventType.ORDER_REFUNDED,
+  ],
+});
+```
+
+## Tree-shaking
+
+Import individual resources for smaller bundles:
+
+```typescript
+import { WebhooksResource } from 'listbee/webhooks';
+import { OrdersResource } from 'listbee/orders';
+```
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).
+
+## Links
+
+- [Documentation](https://docs.listbee.so)
+- [API Reference](https://docs.listbee.so/api)
+- [GitHub](https://github.com/listbee-dev/listbee-typescript)
+- [npm](https://www.npmjs.com/package/listbee)

package/dist/cjs/base-client.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Base HTTP client for the ListBee SDK.
+ */
+import type { ListResponse } from './types/shared';
+/** Options accepted by the ListBee client constructor. */
+export interface ClientOptions {
+    /** Your ListBee API key (lb_...). Falls back to LISTBEE_API_KEY env var. */
+    apiKey?: string;
+    /** API base URL. Default: https://api.listbee.so */
+    baseUrl?: string;
+    /** Default request timeout in milliseconds. Default: 30000 */
+    timeoutMs?: number;
+    /** Max retries on 429/5xx responses. Default: 3 */
+    maxRetries?: number;
+}
+/** Options for individual HTTP requests. */
+export interface RequestOptions {
+    /** Request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Whether to include the Authorization header. Default: true. */
+    authenticated?: boolean;
+}
+/** A cursor page holding one page of results. */
+export declare class CursorPage<T> {
+    readonly object: "list";
+    readonly data: T[];
+    readonly has_more: boolean;
+    readonly cursor: string | null;
+    constructor(body: ListResponse<T>);
+}
+/** Internal HTTP response wrapper. */
+interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/**
+ * Low-level HTTP client with auth, retries, and error handling.
+ */
+export declare class BaseClient {
+    protected readonly _apiKey: string | undefined;
+    protected readonly _baseUrl: string;
+    protected readonly _timeoutMs: number;
+    protected readonly _maxRetries: number;
+    constructor(opts?: ClientOptions);
+    protected _ensureApiKey(): string;
+    protected _buildHeaders(authenticated?: boolean): Record<string, string>;
+    protected _shouldRetry(status: number, attempt: number): boolean;
+    protected _retryDelayMs(attempt: number, headers: Record<string, string>): number;
+    /** Perform an HTTP request with retry logic. */
+    _request(method: string, path: string, opts?: {
+        body?: unknown;
+        params?: Record<string, string | number | boolean>;
+        timeoutMs?: number;
+        authenticated?: boolean;
+    }): Promise<HttpResponse>;
+    get(path: string, params?: Record<string, string | number | boolean>, options?: RequestOptions): Promise<HttpResponse>;
+    post(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
+    put(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
+    patch(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
+    delete(path: string, options?: RequestOptions): Promise<HttpResponse>;
+    getPage<T>(path: string, params: Record<string, string | number | boolean>, parse: (item: unknown) => T, options?: RequestOptions): Promise<CursorPage<T>>;
+}
+export {};