syntro-sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,361 @@
+import type {
+  SyntroConfig,
+  EventType,
+  SyntroEvent,
+  AuthResult,
+  PaymentResult,
+  EventResult,
+  UserResult,
+  MetadataResult,
+  VerifyResult,
+  VerifyPaymentResult,
+  VerifyPaymentOptions,
+} from './types';
+
+export type {
+  SyntroConfig, EventType, SyntroEvent, AuthResult,
+  PaymentResult, EventResult, UserResult, MetadataResult, VerifyResult,
+  VerifyPaymentResult, VerifyPaymentOptions,
+};
+
+/**
+ * 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);
+ * ```
+ */
+export class Syntro {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(apiKey: string, config: SyntroConfig = {}) {
+    if (!apiKey) throw new Error('[Syntro] apiKey is required');
+    this.apiKey = apiKey;
+    this.baseUrl = (config.baseUrl ?? 'https://api.syntro.run').replace(/\/$/, '');
+  }
+
+  // ─── Helpers ────────────────────────────────────────────────────────────────
+
+  private get headers(): Record<string, string> {
+    return { 'Content-Type': 'application/json', Authorization: `Bearer ${this.apiKey}` };
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST', headers: this.headers, body: JSON.stringify(body),
+    });
+    return res.json() as Promise<T>;
+  }
+
+  private async put<T>(path: string, body: unknown): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'PUT', headers: this.headers, body: JSON.stringify(body),
+    });
+    return res.json() as Promise<T>;
+  }
+
+  private async patch<T>(path: string, body: unknown): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'PATCH', headers: this.headers, body: JSON.stringify(body),
+    });
+    return res.json() as Promise<T>;
+  }
+
+  private async del<T>(path: string): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'DELETE', headers: this.headers,
+    });
+    return res.json() as Promise<T>;
+  }
+
+  private async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, String(v)));
+    const res = await fetch(url.toString(), { method: 'GET', headers: this.headers });
+    return res.json() as Promise<T>;
+  }
+
+  // ─── Events ─────────────────────────────────────────────────────────────────
+
+  /**
+   * 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
+   */
+  async event(
+    type: EventType,
+    name: string,
+    message?: string,
+    metadata?: Record<string, unknown>,
+    userId?: string,
+  ): Promise<EventResult> {
+    try {
+      return await this.post<EventResult>('/v1/events', { type, name, message, metadata, userId });
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Track an ERROR event.
+   * @example
+   * await syntro.sendError('checkout_failed', 'Error loading page', { code: 500 });
+   */
+  async sendError(name: string, message?: string, metadata?: Record<string, unknown>): Promise<EventResult> {
+    return this.event('ERROR', name, message, metadata);
+  }
+
+  /** Get event statistics grouped by name (for analytics dashboard). */
+  async getStats(type?: EventType) {
+    return this.get('/v1/events/stats', type ? { type } : {});
+  }
+
+  /** List raw events with pagination. */
+  async listEvents(options?: { type?: EventType; limit?: number; skip?: number }) {
+    return this.get('/v1/events', {
+      ...(options?.type ? { type: options.type } : {}),
+      ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+      ...(options?.skip !== undefined ? { skip: options.skip } : {}),
+    });
+  }
+
+  // ─── Auth ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Register a new end-user.
+   * @example
+   * const { user, token, error } = await syntro.register('john', 'john@email.com', 'pass123');
+   */
+  async register(username: string, email: string, password: string): Promise<AuthResult> {
+    try {
+      const res = await this.post<AuthResult & { error?: string; message?: string }>(
+        '/v1/auth/register', { username, email, password }
+      );
+      return (res.error || res.message && !res.success)
+        ? { success: false, error: res.error ?? res.message }
+        : res;
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Login with username + password.
+   * @example
+   * const { token, user, error } = await syntro.login('john', 'pass123');
+   */
+  async login(username: string, password: string): Promise<AuthResult> {
+    try {
+      const res = await this.post<AuthResult & { error?: string }>('/v1/auth/login', { username, password });
+      return res.error ? { success: false, error: res.error } : res;
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Login with email + password.
+   */
+  async loginWithEmail(email: string, password: string): Promise<AuthResult> {
+    try {
+      const res = await this.post<AuthResult & { error?: string }>('/v1/auth/login', { email, password });
+      return res.error ? { success: false, error: res.error } : res;
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Verify a JWT token and get the associated user.
+   * @example
+   * const { valid, user } = await syntro.verifyToken(token);
+   */
+  async verifyToken(token: string): Promise<VerifyResult> {
+    try {
+      return await this.post<VerifyResult>('/v1/auth/verify', { token });
+    } catch (err) {
+      return { valid: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Get a ProjectUser by ID.
+   * @example
+   * const { user } = await syntro.getUser(userId);
+   */
+  async getUser(userId: string): Promise<UserResult> {
+    try {
+      return await this.get<UserResult>(`/v1/auth/users/${userId}`);
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Get a user's username by ID.
+   * @example
+   * const username = await syntro.getUsername(userId);
+   */
+  async getUsername(userId: string): Promise<string | null> {
+    const { user, error } = await this.getUser(userId);
+    if (error || !user) return null;
+    return user.username ?? null;
+  }
+
+  /**
+   * Get a user's email by ID.
+   * @example
+   * const email = await syntro.getUserEmail(userId);
+   */
+  async getUserEmail(userId: string): Promise<string | null> {
+    const { user, error } = await this.getUser(userId);
+    if (error || !user) return null;
+    return user.email ?? null;
+  }
+
+  /**
+   * Get a user's metadata by ID.
+   * @example
+   * const meta = await syntro.getMetadata(userId);
+   * console.log(meta?.plan, meta?.role);
+   */
+  async getMetadata(userId: string): Promise<Record<string, unknown> | null> {
+    const { user, error } = await this.getUser(userId);
+    if (error || !user) return null;
+    return (user.metadata as Record<string, unknown>) ?? {};
+  }
+
+  /**
+   * Merge-update a user's metadata. Existing keys are preserved.
+   * @example
+   * await syntro.updateMetadata(userId, { plan: 'pro', role: 'admin' });
+   */
+  async updateMetadata(userId: string, metadata: Record<string, unknown>): Promise<MetadataResult> {
+    try {
+      return await this.patch<MetadataResult>(`/v1/auth/users/${userId}/metadata`, metadata);
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Update a user's username or fully replace their metadata.
+   * @example
+   * await syntro.updateUser(userId, { username: 'new_name' });
+   */
+  async updateUser(
+    userId: string,
+    data: { username?: string; metadata?: Record<string, unknown> },
+  ): Promise<UserResult> {
+    try {
+      return await this.put<UserResult>(`/v1/auth/users/${userId}`, data);
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Delete a ProjectUser permanently.
+   * @example
+   * const { success } = await syntro.deleteUser(userId);
+   */
+  async deleteUser(userId: string): Promise<{ success: boolean; error?: string }> {
+    try {
+      return await this.del<{ success: boolean; error?: string }>(`/v1/auth/users/${userId}`);
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /** List users with pagination. */
+  async listUsers(options?: { limit?: number; skip?: number }) {
+    return this.get('/v1/auth/users', {
+      ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+      ...(options?.skip !== undefined ? { skip: options.skip } : {}),
+    });
+  }
+
+  // ─── Billing ─────────────────────────────────────────────────────────────────
+
+  /**
+   * 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;
+   */
+  async createPayment(
+    name: string,
+    amount: number,
+    options?: {
+      currency?: string;
+      successUrl?: string;
+      cancelUrl?: string;
+      customerEmail?: string;
+    },
+  ): Promise<PaymentResult> {
+    try {
+      const res = await this.post<PaymentResult & { error?: string }>('/v1/billing/create-payment', {
+        name, amount,
+        currency: options?.currency ?? 'usd',
+        successUrl: options?.successUrl,
+        cancelUrl: options?.cancelUrl,
+        customerEmail: options?.customerEmail,
+      });
+      return res.error ? { error: res.error } : res;
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+
+  /** List payment transactions. */
+  async listTransactions(options?: { limit?: number; skip?: number; status?: string }) {
+    return this.get('/v1/billing/transactions', {
+      ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+      ...(options?.skip !== undefined ? { skip: options.skip } : {}),
+      ...(options?.status ? { status: options.status } : {}),
+    });
+  }
+
+  /**
+   * 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);
+   */
+  async verifyPayment(customerEmail: string, options?: VerifyPaymentOptions): Promise<VerifyPaymentResult> {
+    try {
+      return await this.get<VerifyPaymentResult>('/v1/billing/verify-payment', {
+        customerEmail,
+        ...(options?.name ? { name: options.name } : {}),
+      });
+    } catch (err) {
+      return { paid: false, error: err instanceof Error ? err.message : 'Unknown error' };
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+export interface SyntroConfig {
+  baseUrl?: string;
+}
+
+export type EventType = 'CUSTOM' | 'ERROR' | 'AUTH';
+
+export interface SyntroEvent {
+  type: EventType;
+  name: string;
+  message?: string;
+  metadata?: Record<string, unknown>;
+  userId?: string;
+}
+
+export interface SyntroUser {
+  id: string;
+  username: string;
+  email: string;
+  createdAt?: string;
+  updatedAt?: string;
+  metadata?: unknown;
+  provider?: string;
+}
+
+export interface AuthResult {
+  success: boolean;
+  user?: SyntroUser;
+  token?: string;
+  error?: string;
+}
+
+export interface UserResult {
+  user?: SyntroUser;
+  success?: boolean;
+  error?: string;
+}
+
+export interface MetadataResult {
+  success: boolean;
+  metadata?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  user?: SyntroUser;
+  error?: string;
+}
+
+export interface PaymentResult {
+  url?: string | null;
+  sessionId?: string;
+  error?: string;
+}
+
+export interface EventResult {
+  success: boolean;
+  eventId?: string;
+  error?: string;
+}
+
+export interface VerifyPaymentResult {
+  paid: boolean;
+  transaction?: {
+    id: string;
+    amount: number;
+    currency: string;
+    createdAt: string;
+  } | null;
+  error?: string;
+}
+
+export interface VerifyPaymentOptions {
+  name?: string;
+}
+

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM"],
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}