syntro-sdk

Official JavaScript/TypeScript SDK for Syntro BaaS.

npm install syntro-sdk

Setup

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

// 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

// Register a new user
const { user, token, error } = await syntro.register(
  'johndoe',           // username
  '[email protected]',  // 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('[email protected]', 'password123');

Token Verification

// 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

// 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. "[email protected]"
const meta     = await syntro.getMetadata(userId);   // e.g. { plan: "pro", role: "admin" }

User Management

// 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

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: '[email protected]',               // 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

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.

const { paid, transaction, error } = await syntro.verifyPayment('[email protected]', {
  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

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 |