npm package: @sutrena/sdk
Description: Official TypeScript SDK for the Sutrena API
Latest version: 0.1.0

# @sutrena/sdk

Official TypeScript SDK for the [Sutrena](https://sutrena.com) API.

Zero runtime dependencies. Works in Node.js 18+, Deno, Bun, and browsers.

## Installation

```bash
npm install @sutrena/sdk
```

## Quick Start

```typescript
import { Sutrena } from "@sutrena/sdk";

// Use an existing API key
const sutrena = new Sutrena("st_live_xxx");

// Or create a free trial instantly (no signup)
const trial = await Sutrena.createTrial();
const s = new Sutrena(trial.key);

// Deploy a page
const { data: page } = await s.pages.create({
  slug: "index",
  title: "My Site",
  html: "<h1>Hello World</h1>",
});
console.log(page.subdomainUrl); // https://your-subdomain.sutrena.com/
```

## Resources

All resources are available as properties on the `Sutrena` instance:

| Resource | Description |
|----------|-------------|
| `pages` | Deploy HTML pages, manage entries |
| `forms` | Create data collection endpoints |
| `submissions` | Search, upsert, export form submissions |
| `dashboards` | Create metric dashboards (7 widget types) |
| `webhooks` | Real-time submission notifications |
| `analytics` | Privacy-first web analytics |
| `subdomains` | Manage subdomains |
| `domains` | Custom domain management |
| `folders` | Organize resources |
| `deploy` | Deploy static sites from zip |
| `account` | Account info and usage |
| `keys` | API key management |
| `assets` | Upload images, CSS, JS to CDN |
| `siteTemplates` | Deploy parameterized site templates |
| `automations` | DSL-based automation pipelines |
| `emails` | Email templates and sending |

## Compound Methods

High-level methods that orchestrate multiple resources in one call:

```typescript
// Deploy a site + enable analytics in one call
// subdomain: finds existing or creates new project — never renames
const { data } = await s.launch({
  pages: [
    { slug: "index", title: "Home", html: "<h1>Hello</h1>" },
    { slug: "about", title: "About", html: "<h1>About</h1>" },
  ],
  subdomain: "my-site",
  analytics: true,
  domain: "mysite.com", // optional: auto-link custom domain (Pro+)
});
console.log(data.subdomainUrl); // https://my-site.sutrena.com
console.log(data.customDomainUrl); // https://mysite.com (when domain is set)

// Create a form + dashboard + webhooks scoped to the same project
const { data: pipeline } = await s.collect({
  name: "Feedback",
  fields: [
    { name: "email", label: "Email", type: "email", required: true },
    { name: "message", label: "Message", type: "textarea" },
  ],
  dashboard: true,
  notify: { slack: "https://hooks.slack.com/services/..." },
  subdomain: "my-site", // scopes form to the project's folder
});
console.log(pipeline.form.formId);

// Get per-project status (or omit subdomain for full account)
const { data: snapshot } = await s.status({ subdomain: "my-site" });
console.log(snapshot.usage, snapshot.pages, snapshot.forms);
```

## Examples

### Create a form and collect data

```typescript
const { data: form } = await s.forms.create({
  name: "Contact Form",
  fields: [
    { name: "email", label: "Email", type: "email", required: true },
    { name: "message", label: "Message", type: "textarea" },
  ],
});

console.log(form.hostedFormUrl); // Share this URL
console.log(form.submitUrl);     // POST submissions here
```

### Create a dashboard

```typescript
const { data: dashboard } = await s.dashboards.create({
  title: "Submissions Overview",
  formId: form.formId,
  dsl: {
    version: 1,
    widgets: [
      { type: "metric_card", title: "Total", value: "count(*)" },
      { type: "pie_chart", title: "By Category", groupBy: "category" },
      { type: "line_chart", title: "Over Time", groupBy: "$submitted_at:day" },
    ],
  },
});
```

### Set up analytics

```typescript
const { data } = await s.analytics.createSite({
  name: "My Site",
  subdomainId: "sub_xxx", // Auto-tracks all pages on this subdomain
});

// Query analytics
const { data: result } = await s.analytics.query({
  siteId: data.site.id,
  metric: "page_views",
  period: "30d",
  breakdownBy: "country",
});
```

### Webhook notifications

```typescript
const { data: webhook } = await s.webhooks.create({
  url: "https://hooks.slack.com/services/...",
  template: "slack",
  formIds: [form.formId],
});
```

## Configuration

```typescript
const s = new Sutrena("st_live_xxx", {
  baseUrl: "https://sutrena.com", // Default
  timeout: 30000,                  // Default 30s
});
```

## Error Handling

```typescript
import { SutrenaApiError, SutrenaTimeoutError } from "@sutrena/sdk";

try {
  await s.pages.create({ slug: "index", title: "Home", html: "<h1>Hi</h1>" });
} catch (e) {
  if (e instanceof SutrenaApiError) {
    console.error(e.status, e.message, e.details);
  } else if (e instanceof SutrenaTimeoutError) {
    console.error("Request timed out");
  }
}
```

## License

MIT