syntro-sdk 1.0.0

package/README.md

@@ -0,0 +1,205 @@
+# syntro-sdk
+
+Official JavaScript/TypeScript SDK for [Syntro](https://syntro.run) BaaS.
+
+```bash
+npm install syntro-sdk
+```
+
+---
+
+## Setup
+
+```typescript
+import { Syntro } from 'syntro-sdk';
+
+const syntro = new Syntro('sk_your_api_key', {
+  baseUrl: 'https://api.syntro.run' // optional, this is the default
+});
+```
+
+---
+
+## Events & Analytics
+
+```typescript
+// Track a custom business event
+await syntro.event('CUSTOM', 'cart_add', 'User added product to cart', {
+  productId: 'prod_123'
+});
+
+// Track an error
+await syntro.sendError('checkout_failed', 'Error loading checkout', {
+  page: '/checkout',
+  statusCode: 500
+});
+
+// Get event stats (for analytics dashboard)
+const stats = await syntro.getStats();
+// { summary: { custom: 12, error: 3, auth: 8, total: 23 }, events: [...] }
+
+// Get stats for a specific type
+const errorStats = await syntro.getStats('ERROR');
+
+// List raw events
+const { events, total } = await syntro.listEvents({ type: 'ERROR', limit: 20 });
+```
+
+---
+
+## Auth (ProjectUsers)
+
+### Register & Login
+
+```typescript
+// Register a new user
+const { user, token, error } = await syntro.register(
+  'johndoe',           // username
+  'john@example.com',  // email
+  'password123'        // password (min 6 chars)
+);
+
+// Login with username
+const { user, token, error } = await syntro.login('johndoe', 'password123');
+
+// Login with email
+const { user, token, error } = await syntro.loginWithEmail('john@example.com', 'password123');
+```
+
+### Token Verification
+
+```typescript
+// Verify a JWT token (e.g. sent in a request header)
+const { valid, user, error } = await syntro.verifyToken(token);
+
+if (valid) {
+  console.log('Authenticated user:', user.username);
+}
+```
+
+### User Info
+
+```typescript
+// Get full user object
+const { user } = await syntro.getUser(userId);
+
+// Quick accessors
+const username = await syntro.getUsername(userId);  // e.g. "johndoe"
+const email    = await syntro.getUserEmail(userId);  // e.g. "john@example.com"
+const meta     = await syntro.getMetadata(userId);   // e.g. { plan: "pro", role: "admin" }
+```
+
+### User Management
+
+```typescript
+// Update a user's username or metadata (replaces metadata)
+await syntro.updateUser(userId, { username: 'new_username' });
+await syntro.updateUser(userId, { metadata: { plan: 'pro' } });
+
+// Merge-update metadata (preserves existing keys)
+await syntro.updateMetadata(userId, { onboardingDone: true });
+
+// Delete a user
+const { success } = await syntro.deleteUser(userId);
+
+// List all users
+const { users, total } = await syntro.listUsers({ limit: 50 });
+```
+
+---
+
+## Billing (Stripe Payments)
+
+### Accepting Payments in 3 Steps
+
+#### Step 1: Configure Stripe in Syntro Dashboard
+Go to **Settings → Stripe** in your Syntro project and add:
+- **Stripe Secret Key** (`sk_live_...`)
+- **Stripe Webhook Secret** (`whsec_...`)
+
+#### Step 2: Add the Webhook in Stripe Dashboard
+In **Stripe → Developers → Webhooks**, create a new endpoint:
+
+```
+URL: https://api.syntro.run/v1/billing/webhook/<YOUR_PROJECT_ID>
+Events to listen for: checkout.session.completed
+```
+
+#### Step 3: Create a Checkout Session in Your App
+
+```typescript
+const { url, error } = await syntro.createPayment('Premium Plan', 999, {
+  currency: 'usd',                                  // optional, default: usd
+  successUrl: 'https://yourapp.com/payment/success', // optional
+  cancelUrl: 'https://yourapp.com/payment/cancel',   // optional
+  customerEmail: 'customer@email.com',               // optional, pre-fills Stripe form
+});
+
+if (error) {
+  console.error('Payment error:', error);
+  return;
+}
+
+// Redirect customer to Stripe Checkout
+window.location.href = url!;
+```
+
+Syntro will automatically:
+1. ✅ Verify the Stripe webhook signature
+2. ✅ Record the transaction in the database
+3. ✅ Log a `payment_completed` CUSTOM event
+4. ✅ Show it in your Transactions dashboard
+
+### List Transactions
+
+```typescript
+const { transactions, total } = await syntro.listTransactions({
+  limit: 50,
+  skip: 0,
+  status: 'paid'  // optional filter
+});
+```
+
+### Verify Payment
+Check if a specific customer has already paid for a product. Great for unlocking digital features after payment.
+
+```typescript
+const { paid, transaction, error } = await syntro.verifyPayment('customer@email.com', {
+  name: 'Premium Plan' // optional: filter by product name
+});
+
+if (paid) {
+  console.log(`Verified! Customer paid on ${transaction.createdAt}`);
+  // Unlock premium features...
+}
+```
+
+---
+
+## API Reference
+
+Full interactive documentation: [api.syntro.run/docs](https://api.syntro.run/docs)
+
+### All Methods
+
+| Method | Description |
+|--------|-------------|
+| `event(type, name, message?, meta?, userId?)` | Track any event |
+| `sendError(name, message?, meta?)` | Shorthand for ERROR events |
+| `getStats(type?)` | Get analytics stats |
+| `listEvents(options?)` | List raw events |
+| `register(username, email, password)` | Register a new user |
+| `login(username, password)` | Login with username |
+| `loginWithEmail(email, password)` | Login with email |
+| `verifyToken(token)` | Verify JWT and get user |
+| `getUser(userId)` | Get full user object |
+| `getUsername(userId)` | Get just the username |
+| `getUserEmail(userId)` | Get just the email |
+| `getMetadata(userId)` | Get user metadata object |
+| `updateMetadata(userId, patch)` | Merge-update metadata |
+| `updateUser(userId, data)` | Update username/metadata |
+| `deleteUser(userId)` | Delete a user |
+| `listUsers(options?)` | List project users |
+| `createPayment(name, amount, options?)` | Create Stripe Checkout → URL |
+| `listTransactions(options?)` | List payment transactions |
+| `verifyPayment(email, options?)` | Verify if a customer has paid |

package/dist/index.d.mts

@@ -0,0 +1,231 @@
+interface SyntroConfig {
+    baseUrl?: string;
+}
+type EventType = 'CUSTOM' | 'ERROR' | 'AUTH';
+interface SyntroEvent {
+    type: EventType;
+    name: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+    userId?: string;
+}
+interface SyntroUser {
+    id: string;
+    username: string;
+    email: string;
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: unknown;
+    provider?: string;
+}
+interface AuthResult {
+    success: boolean;
+    user?: SyntroUser;
+    token?: string;
+    error?: string;
+}
+interface UserResult {
+    user?: SyntroUser;
+    success?: boolean;
+    error?: string;
+}
+interface MetadataResult {
+    success: boolean;
+    metadata?: Record<string, unknown>;
+    error?: string;
+}
+interface VerifyResult {
+    valid: boolean;
+    user?: SyntroUser;
+    error?: string;
+}
+interface PaymentResult {
+    url?: string | null;
+    sessionId?: string;
+    error?: string;
+}
+interface EventResult {
+    success: boolean;
+    eventId?: string;
+    error?: string;
+}
+interface VerifyPaymentResult {
+    paid: boolean;
+    transaction?: {
+        id: string;
+        amount: number;
+        currency: string;
+        createdAt: string;
+    } | null;
+    error?: string;
+}
+interface VerifyPaymentOptions {
+    name?: string;
+}
+
+/**
+ * Syntro SDK — Official JavaScript/TypeScript client for api.syntro.run
+ *
+ * @example
+ * ```ts
+ * import { Syntro } from 'syntro-sdk';
+ * const syntro = new Syntro('sk_your_api_key');
+ *
+ * // Events
+ * await syntro.event('CUSTOM', 'cart_add', 'User added to cart');
+ * await syntro.sendError('checkout_failed', 'Checkout error', { page: '/checkout' });
+ *
+ * // Auth
+ * const { token } = await syntro.login('username', 'password');
+ * const username = await syntro.getUsername(userId);
+ * const email    = await syntro.getUserEmail(userId);
+ * const meta     = await syntro.getMetadata(userId);
+ *
+ * // Billing
+ * const { url } = await syntro.createPayment('Pro Plan', 999);
+ * ```
+ */
+declare class Syntro {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, config?: SyntroConfig);
+    private get headers();
+    private post;
+    private put;
+    private patch;
+    private del;
+    private get;
+    /**
+     * Track an event.
+     * @param type     - 'CUSTOM' | 'ERROR' | 'AUTH'
+     * @param name     - Short event key, e.g. 'cart_add'
+     * @param message  - Optional description
+     * @param metadata - Optional arbitrary JSON
+     * @param userId   - Optional ProjectUser ID
+     */
+    event(type: EventType, name: string, message?: string, metadata?: Record<string, unknown>, userId?: string): Promise<EventResult>;
+    /**
+     * Track an ERROR event.
+     * @example
+     * await syntro.sendError('checkout_failed', 'Error loading page', { code: 500 });
+     */
+    sendError(name: string, message?: string, metadata?: Record<string, unknown>): Promise<EventResult>;
+    /** Get event statistics grouped by name (for analytics dashboard). */
+    getStats(type?: EventType): Promise<unknown>;
+    /** List raw events with pagination. */
+    listEvents(options?: {
+        type?: EventType;
+        limit?: number;
+        skip?: number;
+    }): Promise<unknown>;
+    /**
+     * Register a new end-user.
+     * @example
+     * const { user, token, error } = await syntro.register('john', 'john@email.com', 'pass123');
+     */
+    register(username: string, email: string, password: string): Promise<AuthResult>;
+    /**
+     * Login with username + password.
+     * @example
+     * const { token, user, error } = await syntro.login('john', 'pass123');
+     */
+    login(username: string, password: string): Promise<AuthResult>;
+    /**
+     * Login with email + password.
+     */
+    loginWithEmail(email: string, password: string): Promise<AuthResult>;
+    /**
+     * Verify a JWT token and get the associated user.
+     * @example
+     * const { valid, user } = await syntro.verifyToken(token);
+     */
+    verifyToken(token: string): Promise<VerifyResult>;
+    /**
+     * Get a ProjectUser by ID.
+     * @example
+     * const { user } = await syntro.getUser(userId);
+     */
+    getUser(userId: string): Promise<UserResult>;
+    /**
+     * Get a user's username by ID.
+     * @example
+     * const username = await syntro.getUsername(userId);
+     */
+    getUsername(userId: string): Promise<string | null>;
+    /**
+     * Get a user's email by ID.
+     * @example
+     * const email = await syntro.getUserEmail(userId);
+     */
+    getUserEmail(userId: string): Promise<string | null>;
+    /**
+     * Get a user's metadata by ID.
+     * @example
+     * const meta = await syntro.getMetadata(userId);
+     * console.log(meta?.plan, meta?.role);
+     */
+    getMetadata(userId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Merge-update a user's metadata. Existing keys are preserved.
+     * @example
+     * await syntro.updateMetadata(userId, { plan: 'pro', role: 'admin' });
+     */
+    updateMetadata(userId: string, metadata: Record<string, unknown>): Promise<MetadataResult>;
+    /**
+     * Update a user's username or fully replace their metadata.
+     * @example
+     * await syntro.updateUser(userId, { username: 'new_name' });
+     */
+    updateUser(userId: string, data: {
+        username?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<UserResult>;
+    /**
+     * Delete a ProjectUser permanently.
+     * @example
+     * const { success } = await syntro.deleteUser(userId);
+     */
+    deleteUser(userId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** List users with pagination. */
+    listUsers(options?: {
+        limit?: number;
+        skip?: number;
+    }): Promise<unknown>;
+    /**
+     * Create a Stripe Checkout payment session.
+     * Returns a `url` to redirect the customer to.
+     *
+     * @param name         - Product/payment name
+     * @param amount       - Amount in cents (e.g. 999 = $9.99)
+     * @param options      - currency, successUrl, cancelUrl, customerEmail
+     *
+     * @example
+     * const { url, error } = await syntro.createPayment('Pro Plan', 999);
+     * if (url) window.location.href = url;
+     */
+    createPayment(name: string, amount: number, options?: {
+        currency?: string;
+        successUrl?: string;
+        cancelUrl?: string;
+        customerEmail?: string;
+    }): Promise<PaymentResult>;
+    /** List payment transactions. */
+    listTransactions(options?: {
+        limit?: number;
+        skip?: number;
+        status?: string;
+    }): Promise<unknown>;
+    /**
+     * Verify if a customer has paid for a specific product or any product.
+     *
+     * @example
+     * const { paid, transaction } = await syntro.verifyPayment('customer@email.com');
+     * if (paid) console.log('Customer paid!', transaction.amount);
+     */
+    verifyPayment(customerEmail: string, options?: VerifyPaymentOptions): Promise<VerifyPaymentResult>;
+}
+
+export { type AuthResult, type EventResult, type EventType, type MetadataResult, type PaymentResult, Syntro, type SyntroConfig, type SyntroEvent, type UserResult, type VerifyPaymentOptions, type VerifyPaymentResult, type VerifyResult };

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+interface SyntroConfig {
+    baseUrl?: string;
+}
+type EventType = 'CUSTOM' | 'ERROR' | 'AUTH';
+interface SyntroEvent {
+    type: EventType;
+    name: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+    userId?: string;
+}
+interface SyntroUser {
+    id: string;
+    username: string;
+    email: string;
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: unknown;
+    provider?: string;
+}
+interface AuthResult {
+    success: boolean;
+    user?: SyntroUser;
+    token?: string;
+    error?: string;
+}
+interface UserResult {
+    user?: SyntroUser;
+    success?: boolean;
+    error?: string;
+}
+interface MetadataResult {
+    success: boolean;
+    metadata?: Record<string, unknown>;
+    error?: string;
+}
+interface VerifyResult {
+    valid: boolean;
+    user?: SyntroUser;
+    error?: string;
+}
+interface PaymentResult {
+    url?: string | null;
+    sessionId?: string;
+    error?: string;
+}
+interface EventResult {
+    success: boolean;
+    eventId?: string;
+    error?: string;
+}
+interface VerifyPaymentResult {
+    paid: boolean;
+    transaction?: {
+        id: string;
+        amount: number;
+        currency: string;
+        createdAt: string;
+    } | null;
+    error?: string;
+}
+interface VerifyPaymentOptions {
+    name?: string;
+}
+
+/**
+ * Syntro SDK — Official JavaScript/TypeScript client for api.syntro.run
+ *
+ * @example
+ * ```ts
+ * import { Syntro } from 'syntro-sdk';
+ * const syntro = new Syntro('sk_your_api_key');
+ *
+ * // Events
+ * await syntro.event('CUSTOM', 'cart_add', 'User added to cart');
+ * await syntro.sendError('checkout_failed', 'Checkout error', { page: '/checkout' });
+ *
+ * // Auth
+ * const { token } = await syntro.login('username', 'password');
+ * const username = await syntro.getUsername(userId);
+ * const email    = await syntro.getUserEmail(userId);
+ * const meta     = await syntro.getMetadata(userId);
+ *
+ * // Billing
+ * const { url } = await syntro.createPayment('Pro Plan', 999);
+ * ```
+ */
+declare class Syntro {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, config?: SyntroConfig);
+    private get headers();
+    private post;
+    private put;
+    private patch;
+    private del;
+    private get;
+    /**
+     * Track an event.
+     * @param type     - 'CUSTOM' | 'ERROR' | 'AUTH'
+     * @param name     - Short event key, e.g. 'cart_add'
+     * @param message  - Optional description
+     * @param metadata - Optional arbitrary JSON
+     * @param userId   - Optional ProjectUser ID
+     */
+    event(type: EventType, name: string, message?: string, metadata?: Record<string, unknown>, userId?: string): Promise<EventResult>;
+    /**
+     * Track an ERROR event.
+     * @example
+     * await syntro.sendError('checkout_failed', 'Error loading page', { code: 500 });
+     */
+    sendError(name: string, message?: string, metadata?: Record<string, unknown>): Promise<EventResult>;
+    /** Get event statistics grouped by name (for analytics dashboard). */
+    getStats(type?: EventType): Promise<unknown>;
+    /** List raw events with pagination. */
+    listEvents(options?: {
+        type?: EventType;
+        limit?: number;
+        skip?: number;
+    }): Promise<unknown>;
+    /**
+     * Register a new end-user.
+     * @example
+     * const { user, token, error } = await syntro.register('john', 'john@email.com', 'pass123');
+     */
+    register(username: string, email: string, password: string): Promise<AuthResult>;
+    /**
+     * Login with username + password.
+     * @example
+     * const { token, user, error } = await syntro.login('john', 'pass123');
+     */
+    login(username: string, password: string): Promise<AuthResult>;
+    /**
+     * Login with email + password.
+     */
+    loginWithEmail(email: string, password: string): Promise<AuthResult>;
+    /**
+     * Verify a JWT token and get the associated user.
+     * @example
+     * const { valid, user } = await syntro.verifyToken(token);
+     */
+    verifyToken(token: string): Promise<VerifyResult>;
+    /**
+     * Get a ProjectUser by ID.
+     * @example
+     * const { user } = await syntro.getUser(userId);
+     */
+    getUser(userId: string): Promise<UserResult>;
+    /**
+     * Get a user's username by ID.
+     * @example
+     * const username = await syntro.getUsername(userId);
+     */
+    getUsername(userId: string): Promise<string | null>;
+    /**
+     * Get a user's email by ID.
+     * @example
+     * const email = await syntro.getUserEmail(userId);
+     */
+    getUserEmail(userId: string): Promise<string | null>;
+    /**
+     * Get a user's metadata by ID.
+     * @example
+     * const meta = await syntro.getMetadata(userId);
+     * console.log(meta?.plan, meta?.role);
+     */
+    getMetadata(userId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Merge-update a user's metadata. Existing keys are preserved.
+     * @example
+     * await syntro.updateMetadata(userId, { plan: 'pro', role: 'admin' });
+     */
+    updateMetadata(userId: string, metadata: Record<string, unknown>): Promise<MetadataResult>;
+    /**
+     * Update a user's username or fully replace their metadata.
+     * @example
+     * await syntro.updateUser(userId, { username: 'new_name' });
+     */
+    updateUser(userId: string, data: {
+        username?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<UserResult>;
+    /**
+     * Delete a ProjectUser permanently.
+     * @example
+     * const { success } = await syntro.deleteUser(userId);
+     */
+    deleteUser(userId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** List users with pagination. */
+    listUsers(options?: {
+        limit?: number;
+        skip?: number;
+    }): Promise<unknown>;
+    /**
+     * Create a Stripe Checkout payment session.
+     * Returns a `url` to redirect the customer to.
+     *
+     * @param name         - Product/payment name
+     * @param amount       - Amount in cents (e.g. 999 = $9.99)
+     * @param options      - currency, successUrl, cancelUrl, customerEmail
+     *
+     * @example
+     * const { url, error } = await syntro.createPayment('Pro Plan', 999);
+     * if (url) window.location.href = url;
+     */
+    createPayment(name: string, amount: number, options?: {
+        currency?: string;
+        successUrl?: string;
+        cancelUrl?: string;
+        customerEmail?: string;
+    }): Promise<PaymentResult>;
+    /** List payment transactions. */
+    listTransactions(options?: {
+        limit?: number;
+        skip?: number;
+        status?: string;
+    }): Promise<unknown>;
+    /**
+     * Verify if a customer has paid for a specific product or any product.
+     *
+     * @example
+     * const { paid, transaction } = await syntro.verifyPayment('customer@email.com');
+     * if (paid) console.log('Customer paid!', transaction.amount);
+     */
+    verifyPayment(customerEmail: string, options?: VerifyPaymentOptions): Promise<VerifyPaymentResult>;
+}
+
+export { type AuthResult, type EventResult, type EventType, type MetadataResult, type PaymentResult, Syntro, type SyntroConfig, type SyntroEvent, type UserResult, type VerifyPaymentOptions, type VerifyPaymentResult, type VerifyResult };