@simata/sdk

Official TypeScript SDK for Simata Backend Platform

Tenant-scoped SDK for building applications on top of Simata. Includes payment gateway, media management, webhooks, OAuth authentication, and data protection utilities.

⚠️ For Internal Development Only
This SDK is maintained by Simata internal team. Public documentation focuses on usage, not development workflows.

Installation

npm install @simata/sdk zod

pnpm add @simata/sdk zod

Quick Start

1. Authentication (OAuth)

import { SimataOAuth } from "@simata/sdk";

const oauth = new SimataOAuth({
  issuer: "https://api.simata.id",
  clientId: "your-client-id",
  redirectUri: "https://yourapp.com/callback",
});

// Redirect to Simata login
const authUrl = await oauth.getAuthorizationUrl();
window.location.href = authUrl;

// Handle callback
const token = await oauth.handleCallback(window.location.href);

2. Payment Gateway

import { SimataClient } from "@simata/sdk";

const simata = new SimataClient({
  apiKey: "your-api-key",
  baseUrl: "https://api.simata.id",
});

// Create payment
const payment = await simata.payment.create({
  app_id: "your-app-uuid",
  gateway: "midtrans",
  order_id: "ORDER-001",
  amount: 150000,
  currency: "IDR",
  customer_details: {
    name: "John Doe",
    email: "[email protected]",
  },
  return_url: "https://yourapp.com/payment/success",
});

// Check status
const status = await simata.payment.getById(payment.id);

// Wait for completion
const final = await simata.payment.waitForStatus(payment.id, {
  interval: 3000,
  timeout: 300000,
});

3. Media Management

import { mediaClient } from "@simata/sdk";

// Upload file
const file = document.querySelector('input[type="file"]').files[0];
const media = await mediaClient.upload(
  "https://api.simata.id",
  "your-token",
  file
);

// List media
const list = await mediaClient.list("https://api.simata.id", "your-token", {
  page: 1,
  limit: 20,
});

// Delete media
await mediaClient.delete("https://api.simata.id", "your-token", media.id);

4. Webhooks

import { webhookClient } from "@simata/sdk";

// Create webhook
const webhook = await webhookClient.create(
  "https://api.simata.id",
  "your-token",
  {
    name: "Payment Notifications",
    target_url: "https://yourapp.com/webhooks/payment",
    events: ["payment.success", "payment.failed"],
    is_active: true,
  }
);

// List webhooks
const webhooks = await webhookClient.list("https://api.simata.id", "your-token");

// Get statistics
const stats = await webhookClient.getStatistics("https://api.simata.id", "your-token");

5. API Key Management

import { apiKeyClient } from "@simata/sdk";

// Set rotation policy
await apiKeyClient.setRotationPolicy(
  "https://api.simata.id",
  "your-token",
  "your-app-id",
  {
    interval: "90days",
    auto_rotate: true,
  }
);

// Remove rotation policy
await apiKeyClient.removeRotationPolicy(
  "https://api.simata.id",
  "your-token",
  "your-app-id"
);

Available Clients

✅ Tenant-Scoped Operations

| Client | Purpose | Scope | |--------|---------|-------| | SimataOAuth | OAuth PKCE authentication | Public | | payment | Payment gateway (Midtrans, Xendit) | Tenant | | mediaClient | File upload & management | Tenant | | webhookClient | Webhook CRUD & logs | Tenant | | apiKeyClient | API key rotation policy | Tenant | | ProtectionEngine | Data masking & audit | Tenant |

❌ Not Available in SDK

Admin operations are not exposed in public SDK:

• User management (use OAuth)
• App creation/deletion (admin panel only)
• System settings (admin panel only)
• Schema migrations (admin panel only)
• Token management (admin panel only)

Data Protection

import { ProtectionEngine, generateTestKey } from "@simata/sdk";

const adapter = {
  fetchStream: async function* (limit: number, offset: number) {
    yield { id: "1", name: "John Doe", email: "[email protected]" };
  },
  getSchema: () => ["id", "name", "email"],
};

const result = await ProtectionEngine.execute(adapter, {
  limit: 50,
  columns: ["name", "email"],
  salt: "custom-salt",
  config: {
    apiKey: generateTestKey(24 * 60 * 60 * 1000), // Dev only
  },
});

TypeScript Types

import type {
  PaymentResponse,
  CreatePaymentInput,
  IMedia,
  IWebhookEndpoint,
  RotationPolicy,
} from "@simata/sdk";

Zod Schemas

import { payment } from "@simata/sdk";

payment.CreatePaymentSchema.parse(input);
payment.PaymentResponseSchema.parse(response);
payment.WebhookPayloadSchema.parse(webhook);

Security

API Key Format

SMT.<base64-payload>.<signature>

Payload structure:

{
  "exp": 1234567890000
}

Test Keys (Development Only)

import { generateTestKey } from "@simata/sdk";

// Throws error in production
const apiKey = generateTestKey(60 * 60 * 1000);

Webhook Verification

// Server-side only
const payload = await simata.payment.verifyWebhook(
  rawBody,
  signature,
  "webhook-secret"
);

Error Handling

try {
  const payment = await simata.payment.create(data);
} catch (error) {
  if (error.message.includes("UNAUTHORIZED_ACCESS")) {
    // Invalid API key
  } else if (error.message.includes("KEY_EXPIRED")) {
    // Rotate API key
  } else {
    // Other errors
  }
}

UUID Policy

All IDs are UUID strings:

• app_id: string
• payment.id: string
• media.id: string
• webhook.id: string

Payment Statuses

import { isTerminalState, isPendingOrProcessing, canTransitionTo } from "@simata/sdk";

isTerminalState("success"); // true
isPendingOrProcessing("pending"); // true
canTransitionTo("pending", "processing"); // true

Available statuses:

• pending → processing, expired, cancelled
• processing → success, failed
• success → refunded
• failed, refunded, expired, cancelled (terminal)

Examples

Next.js App Router

// app/payment/route.ts
import { SimataClient } from "@simata/sdk";

export async function POST(req: Request) {
  const simata = new SimataClient({
    apiKey: process.env.SIMATA_API_KEY!,
    baseUrl: process.env.SIMATA_URL!,
  });

  const payment = await simata.payment.create({
    app_id: process.env.SIMATA_APP_ID!,
    gateway: "midtrans",
    order_id: `ORDER-${Date.now()}`,
    amount: 150000,
  });

  return Response.json(payment);
}

React Hook

import { mediaClient } from "@simata/sdk";
import { useState } from "react";

function useMediaUpload() {
  const [uploading, setUploading] = useState(false);

  const upload = async (file: File) => {
    setUploading(true);
    try {
      const media = await mediaClient.upload(
        process.env.NEXT_PUBLIC_SIMATA_URL!,
        getToken(),
        file
      );
      return media;
    } finally {
      setUploading(false);
    }
  };

  return { upload, uploading };
}

Support

• Documentation: https://docs.simata.id
• API Reference: https://api.simata.id/docs/api
• Issues: Internal team only

License

Proprietary - Simata Platform © 2026