samva 0.0.1 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,13 @@
+# Samva SDK consumer guide
+
+Use `createClient` from `samva` for Promise applications. Ergonomic methods return decoded values
+and throw `SamvaApiError` subclasses; use `client.raw` only when request and response envelopes are
+required.
+
+Effect applications should import Pascal-cased domain modules from focused subpaths such as
+`samva/effect/email` and provide `Client.layerFetch` from `samva/effect/client`. Install the optional
+peer `effect@4.0.0-beta.102` when using those entrypoints. Keep that exact beta pinned. Tagged API
+failures remain in the Effect error channel and can be handled with `Effect.catchTag`.
+
+Treat exported request and response types as the API contract. Do not import package-internal files
+or generated implementation paths; use only the subpaths declared in `package.json`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arya Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,402 @@
 # samva
 
-To install dependencies:
+TypeScript SDK for Samva's public customer API.
+
+## Documentation
+
+See [AGENTS.md](./AGENTS.md) for concise guidance when using this package with coding agents.
+
+## Overview
+
+The root entrypoint is Promise-based:
+
+```typescript
+import { createClient } from "samva";
+```
+
+The same Promise SDK is also available at `samva/promises`. Native Effect users import domain modules such as `samva/effect/email` and provide `samva/effect/client`. Both clients are generated from Samva's public OpenAPI document, while the Effect runtime does not wrap or execute the Promise client. Effect is an optional peer dependency, so Promise-only applications do not install or load it.
+
+## Installation
 
 ```bash
-bun install
+npm install samva
+# or
+bun add samva
+# or
+yarn add samva
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from "samva";
+
+const client = createClient({
+  baseUrl: "https://api.samva.dev",
+  apiKey: "<samva-api-key>",
+});
+
+const contact = await client.contacts.findOrCreate({
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+});
+
+const message = await client.messages.send({
+  to: [contact],
+  channel: "email",
+  email: {
+    subject: "Hello",
+    html: "<p>Hello World</p>",
+    text: "Hello World",
+  },
+  metadata: {
+    externalUserId: "user_123",
+  },
+});
+
+const messages = await client.messages.list({
+  page: "1",
+  limit: "20",
+});
 ```
 
-To run:
+## Effect Quick Start
+
+Install `effect` next to `samva` when using the Effect entrypoint:
 
 ```bash
-bun run index.ts
+bun add samva effect@4.0.0-beta.102
+```
+
+```typescript
+import { Effect } from "effect";
+import * as Client from "samva/effect/client";
+import * as Email from "samva/effect/email";
+
+const program = Email.send({
+  to: "ada@example.com",
+  subject: "Welcome",
+  html: "<h1>Welcome to Samva</h1>",
+}).pipe(Effect.provide(Client.layerFetch({ apiKey: "<samva-api-key>" })));
+
+const message = await Effect.runPromise(program);
+```
+
+## Authentication
+
+Samva supports two client auth modes. Use one per `createClient` instance.
+
+### API key (automation, CI, single org)
+
+```typescript
+const client = createClient({
+  apiKey: "samva_sk_live_...",
+  baseUrl: "https://api.samva.dev",
+});
 ```
 
-This project was created using `bun init` in bun v1.3.0. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+- `X-API-Key` is configured automatically from `apiKey`.
+- Organization context is derived from the API key — do not send `x-org-slug`.
+
+### OAuth bearer (interactive, multi-org)
+
+```typescript
+const client = createClient({
+  authToken: sessionAccessToken,
+  baseUrl: "https://api.samva.dev",
+  headers: { "x-org-slug": "your-org-slug" },
+});
+```
+
+- Requests use `Authorization: Bearer <authToken>`.
+- The token is user-scoped; send the target organization slug on every request via the `x-org-slug` header.
+- There is no SDK `orgSlug` helper — pass the header directly.
+
+For terminal workflows (`samva login`, `samva org use`, `samva email send --dry-run`), see the [`@samva/cli` README](https://github.com/AryaLabsHQ/samva/tree/main/packages/cli).
+
+## Service Surface
+
+The Promise client exposes:
+
+- `apiKeys`
+- `campaigns`
+- `contacts`
+- `conversations`
+- `design`
+- `email`
+- `messages`
+- `operations`
+- `organizations`
+- `scheduledMessages`
+- `templates`
+- `webhooks`
+
+The Effect SDK exposes Pascal-cased domain modules with lower-camel operations:
+
+- `ApiKeys`
+- `Campaigns`
+- `Contacts`
+- `Conversations`
+- `Design`
+- `Email`
+- `Messages`
+- `Operations`
+- `Organizations`
+- `ScheduledMessages`
+- `Templates`
+- `Webhooks`
+
+Effect operations take direct parameter objects: body, path, and query fields are not wrapped in `payload` or `params` envelopes. Import the modules you use from `samva/effect/<lower-kebab>` and provide `Client.layerFetch` once at the program boundary. `Client.raw` exposes the underlying generated client for advanced access, but ordinary workflows do not require it.
+
+Effect failures carry Samva's real tagged errors (`RateLimitedError`, `ValidationError`, `PaymentRequiredError`, …) directly in the error channel, so `Effect.catchTag("RateLimitedError", …)` works against any operation without enumerating status codes, and each error exposes its own fields (no wrapper `cause`). The SDK also exports category helpers such as `isRetryable`, `isTransient`, `catchAuthError`, and `catchTransient`. Success values decode to domain types: annotated absolute instants become `Date`, sensitive fields become `Redacted`, and unannotated wire timestamps remain strings.
+
+### Default-on retry
+
+The Effect client retries safe operations out of the box, so you do not wrap calls in `Effect.retry`:
+
+- **What retries** — read operations (`GET`/`HEAD`) and sends. Sends are safe because the client attaches an `Idempotency-Key` (below), so the server deduplicates a replayed attempt. Every other mutating operation (`create`, `update`, `remove`, …) is keyless and is never auto-retried.
+- **When** — only for `isRetryable` failures: throttling (`429`), transient server errors (including a transient `BillingProviderError`), and request-transport failures. `ValidationError`, `ConflictError`, `NotFound`, auth, and billing-limit `PaymentRequiredError` failures never retry.
+- **How** — jittered exponential backoff, bounded to four attempts total. A `429` honors the server's `retryAfterSeconds` hint (capped at 60s) in place of the computed delay.
+
+Retry policy is read from context via the `Retry.Service` service. When it is absent, the default applies, so no operation gains a requirement. Override it with a Layer:
+
+```typescript
+import { Effect } from "effect";
+import { isRetryable } from "samva/effect/categories";
+import * as Retry from "samva/effect/retry";
+
+// Turn auto-retry off for a program:
+program.pipe(Effect.provide(Retry.layerDisabled));
+
+// Or install a custom policy (any Effect.retry options):
+program.pipe(Effect.provide(Retry.layer({ times: 6, while: isRetryable })));
+```
+
+### Idempotency keys
+
+Each `messages.send` / `email.send` call generates an `Idempotency-Key` per logical call — stable across the built-in retries, distinct across calls — so a retried send never delivers twice. Pass an explicit key for cross-process deduplication (safe to replay the same request from a different machine):
+
+```typescript
+const send = Email.send(input, { idempotencyKey: "order-4417-receipt" });
+```
+
+Reusing a key with identical content replays the original response; reusing it with different content fails with `ConflictError`.
+
+### Stream pagination
+
+Every list operation that returns the uniform `{ items, pagination: { page, limit, total, totalPages } }` envelope carries two `Stream` companions, so you traverse pages without hand-rolling a `page` loop:
+
+- **`list.items(input?)`** — a `Stream` of individual items across all pages.
+- **`list.pages(input?)`** — a `Stream` of raw page envelopes.
+
+```typescript
+import { Stream } from "effect";
+import * as Contacts from "samva/effect/contacts";
+
+// Every contact, one page fetched at a time:
+const allContacts = Stream.runCollect(Contacts.list.items());
+
+// Bounded consumption is lazy — this fetches only as many pages as it needs:
+const firstFifty = Stream.runCollect(Contacts.list.items().pipe(Stream.take(50)));
+
+// Caller params (start page, limit, filters) are respected:
+const activeFrom2 = Contacts.list.items({ page: "2", limit: "100", status: "active" });
+```
+
+The companions are attached uniformly to every paginated list, including `Messages.list`, `Contacts.list`, `Campaigns.list`, `Email.listDomains`, and `Webhooks.list`. Each page fetch reuses the ambient `Retry` policy. Reads retry per page; pagination does not nest retries. Page and limit inputs retain their OpenAPI wire-string representation. The Promise client is unchanged; stream pagination is Effect-only.
+
+### Redacted secrets
+
+Secret-bearing response fields — the plaintext API key returned by `apiKeys.create` / `apiKeys.rotate`, and the webhook signing secret from `webhooks.regenerateSecret` — decode to `Redacted<string>` on the Effect surface. The secret never leaks through logs, `String(...)`, or `JSON.stringify`; unwrap it explicitly with `Redacted.value` when you need the plaintext:
+
+```typescript
+import { Effect, Redacted } from "effect";
+import * as ApiKeys from "samva/effect/api-keys";
+
+const inspectKey = Effect.gen(function* () {
+  const created = yield* ApiKeys.create({ name: "CI" });
+  `${created.key}`; // "<redacted>" — safe to log
+  return Redacted.value(created.key); // the plaintext key, unwrapped on purpose
+});
+```
+
+The wire body and the Promise client keep plain strings; only the Effect surface is `Redacted`.
+
+## OpenAPI vendor extensions
+
+The published `openapi.json` carries machine-readable semantics on top of the standard schema, derived from the same contract annotations the Effect SDK uses (no second taxonomy):
+
+| Extension      | Where             | Meaning                                                                                           |
+| -------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
+| `x-category`   | error schemas     | The error's semantic categories (e.g. `["throttling", "transient"]`). Omitted when uncategorized. |
+| `x-retryable`  | error schemas     | `true` when the error is safe to retry.                                                           |
+| `x-idempotent` | operations        | `true` when the operation accepts an `Idempotency-Key` header.                                    |
+| `x-sensitive`  | schema properties | `true` for secret-bearing fields (plain `string` on the wire; `Redacted` in the Effect SDK).      |
+
+These let MCP and third-party consumers read retry/idempotency/secret semantics straight from the spec.
+
+## Usage Examples
+
+### Send Email Through Unified Messages
+
+```typescript
+const contact = await client.contacts.findOrCreate({
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+});
+
+const response = await client.messages.send({
+  to: [contact],
+  channel: "email",
+  email: {
+    subject: "Welcome",
+    html: "<h1>Welcome to Samva</h1>",
+    text: "Welcome to Samva",
+  },
+  metadata: {
+    campaign: "welcome",
+  },
+});
+```
+
+### Native Effect Send Email
+
+```typescript
+import * as Email from "samva/effect/email";
+
+const message =
+  yield *
+  Email.send({
+    to: "ada@example.com",
+    subject: "Welcome",
+    html: "<h1>Welcome to Samva</h1>",
+  });
+```
+
+### List Conversations
+
+```typescript
+const response = await client.conversations.list({
+  page: "1",
+  limit: "20",
+  status: "active",
+});
+```
+
+### Schedule a Message
+
+```typescript
+const scheduled = await client.scheduledMessages.create({
+  send: {
+    to: [{ email: "ada@example.com" }],
+    channel: "email",
+    email: { subject: "Reminder", html: "<p>See you tomorrow.</p>" },
+  },
+  scheduledFor: "2026-08-01T09:00:00Z",
+});
+
+// Later, cancel it before it dispatches
+await client.scheduledMessages.cancel({ id: scheduled.id });
+```
+
+### Create and Run a Campaign
+
+```typescript
+const campaign = await client.campaigns.create({
+  name: "August newsletter",
+  channel: "email",
+  content: {
+    channel: "email",
+    email: { subject: "What's new", html: "<h1>Updates</h1>" },
+  },
+  audience: { includeTags: ["subscribers"], excludeTags: ["bounced"] },
+});
+
+const run = await client.campaigns.scheduleRun({
+  id: campaign.id,
+  scheduledFor: "2026-08-01T09:00:00Z",
+});
+
+const recipients = await client.campaigns.listRecipients({
+  id: campaign.id,
+  runId: run.id,
+});
+```
+
+### Custom Headers
+
+```typescript
+const client = createClient({
+  apiKey: "<samva-api-key>",
+  headers: {
+    "X-Custom-Header": "value",
+  },
+});
+```
+
+### Error Handling
+
+```typescript
+import { RateLimitedError, SamvaApiError, SamvaTransportError } from "samva";
+
+try {
+  const message = await client.email.send({
+    to: "ada@example.com",
+    subject: "Test",
+    html: "<p>Test</p>",
+  });
+  console.log(message.id);
+} catch (error) {
+  if (error instanceof RateLimitedError) {
+    console.error(`Retry after ${error.retryAfterSeconds} seconds`);
+  } else if (error instanceof SamvaApiError) {
+    console.error(error._tag, error.status, error.message);
+  } else if (error instanceof SamvaTransportError) {
+    console.error("Transport failure", error.cause);
+  } else {
+    throw error;
+  }
+}
+```
+
+Every ergonomic method returns its decoded success value and throws a generated `SamvaApiError`
+subclass for failures declared by OpenAPI. Network and malformed-response failures throw
+`SamvaTransportError`.
+
+### Raw response access
+
+```typescript
+const result = await client.raw.messages.send({
+  body: {
+    to: [{ contactId: "contact-id" }],
+    channel: "sms",
+    sms: { text: "Hello" },
+  },
+});
+
+if (result.error) console.error(result.response?.status, result.error);
+```
+
+Use `client.raw` only when you need the generated `{ data, error, request, response }` envelope or
+transport-level request options.
+
+## Type Safety
+
+All request and response types are generated from OpenAPI schemas:
+
+```typescript
+import type { MessagesSendData } from "samva";
+
+const requestData: MessagesSendData = {
+  body: {
+    to: [{ contactId: "contact-id" }],
+    channel: "email",
+    email: {
+      subject: "Hello",
+      html: "<p>Hello World</p>",
+    },
+  },
+};
+
+const response = await client.messages.send(requestData.body);
+```

package/dist/categories-CsUa8ojo.js

@@ -0,0 +1,143 @@
+import { Effect } from "effect";
+import * as Predicate$1 from "effect/Predicate";
+//#region src/effect/generated-metadata.ts
+const SamvaErrorMetadata = {
+	BillingProviderError: {
+		categories: ["transient"],
+		retryable: true
+	},
+	ConflictError: {
+		categories: ["conflict"],
+		retryable: false
+	},
+	EmailChannelError: {
+		categories: [],
+		retryable: false
+	},
+	ExternalServiceError: {
+		categories: ["transient"],
+		retryable: true
+	},
+	FlagDisabledError: {
+		categories: [],
+		retryable: false
+	},
+	ForbiddenError: {
+		categories: ["auth"],
+		retryable: false
+	},
+	InternalError: {
+		categories: ["transient"],
+		retryable: true
+	},
+	PaymentRequiredError: {
+		categories: ["billing"],
+		retryable: false
+	},
+	RateLimitedError: {
+		categories: ["throttling", "transient"],
+		retryable: true
+	},
+	ResourceNotFoundError: {
+		categories: ["notFound"],
+		retryable: false
+	},
+	UnauthorizedError: {
+		categories: ["auth"],
+		retryable: false
+	},
+	ValidationError: {
+		categories: ["validation"],
+		retryable: false
+	},
+	WebhookEnqueueError: {
+		categories: ["transient"],
+		retryable: true
+	}
+};
+//#endregion
+//#region src/effect/categories.ts
+/**
+* Semantic error-category helpers for the Effect SDK.
+*
+* Every operation's error channel carries the server's real tagged errors
+* ({@link import("./index").ConflictError} …). These helpers let callers catch
+* or test by *category* — auth, validation, throttling, transient … — without
+* enumerating tags, and cover the raw transport/decode errors too. The category
+* assignments are generated from the OpenAPI category extensions.
+*
+* @example
+* ```ts
+* import { catchAuthError, isRetryable } from "samva/effect";
+*
+* samva.messages.send(input).pipe(
+*   catchAuthError((error) => Effect.logError(`auth failed: ${error.message}`)),
+*   Effect.retry({ while: isRetryable }),
+* );
+* ```
+*/
+const emailChannelCategories = (reason) => {
+	switch (reason) {
+		case "auth": return ["auth"];
+		case "rejected": return ["validation"];
+		case "rate_limited": return ["throttling", "transient"];
+		case "transport": return ["transient"];
+		default: return [];
+	}
+};
+const categoriesOf = (error) => {
+	if (!Predicate$1.isObject(error) || typeof error._tag !== "string") return [];
+	if (error._tag === "EmailChannelError") return emailChannelCategories(error.reason);
+	return SamvaErrorMetadata[error._tag]?.categories ?? [];
+};
+const hasCategory = (error, category) => categoriesOf(error).includes(category);
+const isRetryableError = (error) => {
+	if (!Predicate$1.isObject(error) || typeof error._tag !== "string") return false;
+	if (error._tag === "EmailChannelError") return categoriesOf(error).includes("transient");
+	return SamvaErrorMetadata[error._tag]?.retryable ?? false;
+};
+const categoryGuard = (category) => (error) => hasCategory(error, category);
+const isAuthError = categoryGuard("auth");
+const isValidationError = categoryGuard("validation");
+const isNotFoundError = categoryGuard("notFound");
+const isConflictError = categoryGuard("conflict");
+const isThrottlingError = categoryGuard("throttling");
+const isBillingError = categoryGuard("billing");
+/**
+* Network-level request failure (no HTTP response). Only `TransportError` is
+* transient/retryable: `EncodeError` and `InvalidUrlError` are deterministic
+* programmer errors (bad input, bad URL) that would fail identically on every
+* attempt — retrying them would loop forever.
+*/
+const isRequestTransportError = (error) => {
+	if (!Predicate$1.isTagged(error, "HttpClientError")) return false;
+	const reason = error.reason;
+	return Predicate$1.isObject(reason) && Predicate$1.isTagged(reason, "TransportError");
+};
+/** True for transient failures, including raw request-transport errors (D4). */
+const isTransient = (error) => hasCategory(error, "transient") || isRequestTransportError(error);
+/** True when an error is declared safe to retry (throttling / transient / transport). */
+const isRetryable = (error) => isRetryableError(error) || isRequestTransportError(error);
+/**
+* Catch every error in `category`. The handler receives the category's error
+* union — including `EmailChannelError` where its `reason` can place it in the
+* category — while only total-membership classes are narrowed out of the error
+* channel (`EmailChannelError` stays: instances with other reasons pass through).
+*/
+const catchCategory = (category, handler) => (effect) => Effect.catchIf(effect, (error) => hasCategory(error, category), handler);
+const catchAuthError = (handler) => catchCategory("auth", handler);
+const catchValidationError = (handler) => catchCategory("validation", handler);
+const catchNotFoundError = (handler) => catchCategory("notFound", handler);
+const catchConflictError = (handler) => catchCategory("conflict", handler);
+const catchThrottlingError = (handler) => catchCategory("throttling", handler);
+const catchBillingError = (handler) => catchCategory("billing", handler);
+/**
+* Catch transient failures — including raw request-transport errors — for
+* fallback/degrade paths. The declared error channel is left intact because
+* transient covers untyped transport errors as well.
+*/
+const catchTransient = (handler) => (effect) => Effect.catchIf(effect, (error) => isTransient(error), handler);
+//#endregion
+export { isTransient as _, catchNotFoundError as a, catchValidationError as c, isAuthError as d, isBillingError as f, isThrottlingError as g, isRetryable as h, catchConflictError as i, categoriesOf as l, isNotFoundError as m, catchBillingError as n, catchThrottlingError as o, isConflictError as p, catchCategory as r, catchTransient as s, catchAuthError as t, hasCategory as u, isValidationError as v };
+
+//# sourceMappingURL=categories-CsUa8ojo.js.map

package/dist/client/client/client.gen.d.ts

@@ -0,0 +1,2 @@
+import type { Client, Config } from "./types.gen";
+export declare const createClient: (config?: Config) => Client;

package/dist/client/client/index.d.ts

@@ -0,0 +1,10 @@
+export type { Auth } from "../core/auth.gen";
+export type { QuerySerializerOptions } from "../core/bodySerializer.gen";
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from "../core/bodySerializer.gen";
+export { buildClientParams } from "../core/params.gen";
+export { serializeQueryKeyValue } from "../core/queryKeySerializer.gen";
+export type { ServerSentEventsResult } from "../core/serverSentEvents.gen";
+export type { ClientMeta } from "../core/types.gen";
+export { createClient } from "./client.gen";
+export type { Client, ClientOptions, Config, CreateClientConfig, Options, RequestOptions, RequestResult, ResolvedRequestOptions, ResponseStyle, TDataShape, } from "./types.gen";
+export { createConfig, mergeHeaders } from "./utils.gen";