@durgadigital/narada 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Durga Digital
+
+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,3 +1,90 @@
-# Temporary Holding Version
+# Narada Node SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed, dependency-free, server-side client for your Narada installation. Requires Node.js 22+. MIT licensed.
+
+```sh
+npm install @durgadigital/narada
+```
+
+From the monorepo:
+
+```sh
+pnpm --filter @durgadigital/narada build
+pnpm --filter @durgadigital/narada pack
+```
+
+Install the resulting `durgadigital-narada-0.1.0.tgz` in another application with `npm install /path/to/durgadigital-narada-0.1.0.tgz`. Inside this workspace, declare `"@durgadigital/narada": "workspace:*"` and build the SDK first. The archive includes JavaScript and TypeScript declarations; it does not require the Narada server source or TypeScript at runtime. This release provides an ESM entry point.
+
+```js
+import { Narada, NaradaError } from "@durgadigital/narada";
+
+const narada = new Narada({
+  baseUrl: "http://localhost:5173", // dashboard origin, without /api/v1
+  apiKey: process.env.NARADA_API_KEY,
+  timeoutMs: 30000,
+});
+
+const result = await narada.emails.send(
+  {
+    from: "hello@narada.test",
+    to: "alex@example.com",
+    subject: "Welcome",
+    text: "Your account is ready.",
+  },
+  { idempotencyKey: "welcome-user-123" },
+);
+
+try {
+  console.log(await narada.emails.get(result.id));
+} catch (error) {
+  if (error instanceof NaradaError) {
+    console.error(error.status, error.code, error.requestId);
+  } else throw error;
+}
+```
+
+Resources: `templates`, `emails`, `broadcasts`, `contacts`, `contactProperties`, `segments`, and `topics`. `send` remains an alias for `emails.send`. Management resources require a **Full access** API key; existing and default keys retain email sending/status access only. Use keys on your server, never in a browser bundle.
+
+List methods return `{ data, nextCursor }`. Pass `{ limit: 20, cursor: previous.nextCursor }` to continue. A null cursor ends the list. Lists are eventually consistent, not a transactionally frozen view.
+
+Update methods require the latest `revision` and a full resource input (`draft`, `contact`, `property`, `segment`, or `topic`), not a patch. Fetch again after a 409; do not overwrite another writer blindly. Contacts are addressed by email; properties by key; other resources by UUID.
+
+```js
+const topic = await narada.topics.create({ name: "Product updates" });
+const segment = await narada.segments.create({
+  name: "Customers",
+  kind: "manual",
+});
+await narada.segments.import(segment.id, {
+  csv: "email,first_name\nalex@example.com,Alex",
+  consentSource: "Explicit signup form",
+  consentConfirmed: true,
+  topicIds: [topic.id],
+});
+const broadcast = await narada.broadcasts.create({
+  name: "October update",
+  audienceId: segment.id,
+  topicId: topic.id,
+  from: "hello@narada.test",
+  subject: "Hello {{contact.first_name}}",
+  text: "Here is the latest news.",
+  organization: "Example company",
+  postalAddress: "123 Example Street, Sydney NSW 2000",
+});
+console.log(await narada.broadcasts.preview(broadcast.id));
+// Queues delivery to eligible recipients; use the current revision after any edits.
+await narada.broadcasts.send(broadcast.id, {
+  revision: broadcast.revision,
+  confirmed: true,
+});
+```
+
+Requests time out after 30 seconds by default and are **never retried automatically**. Network/abort errors propagate; HTTP errors throw `NaradaError` with `status`, `code`, `requestId`, and optional `retryAfter` seconds. A timeout does not imply the server rejected a mutation. Only email submission supports `Idempotency-Key`; reuse it for retries. Broadcast launch is guarded by revision and state—retrieve it after an uncertain outcome. Creating resources, duplicating broadcasts, and test sends have no idempotency guarantee.
+
+Use `fetch` in constructor options to inject a test transport. An optional `signal` is supported on `emails.send`. API keys are not forwarded across redirects.
+
+See the dashboard API reference for copyable Node.js and cURL examples for every supported operation. Automations, property deletion, and whole-contact/segment deletion are not supported in this release. Topics can be archived with `topics.update`.
+
+## Templates
+
+Use `templates.create`, `get`, `list`, `update`, `publish`, `preview`, `test`, `duplicate`, `archive`, and `createBroadcast` with a Full access key. Updates/publication require the latest revision. Sending keys can use `emails.send({from, to, template: {id: "welcome-email", version: 1, variables: {first_name: "Alex"}}})`. Pin the publication version to keep retries stable. Draft changes do not affect published content or already accepted emails.

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+import type * as T from "./types.js";
+export type * from "./types.js";
+export declare class NaradaError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, status: number, code?: string | undefined, requestId?: string | undefined, retryAfter?: number | undefined);
+}
+export interface NaradaOptions {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+/** Server-side client. Requests are never retried implicitly, including timeouts. */
+export declare class Narada {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly transport;
+    constructor(options: NaradaOptions);
+    private request;
+    /** Backward-compatible alias for emails.send. */
+    send: (input: T.EmailInput | T.TemplateEmailInput, options?: RequestOptions) => Promise<T.EmailAccepted>;
+    templates: {
+        list: (options?: T.ListOptions) => Promise<T.Page<T.Template>>;
+        get: (id: string) => Promise<T.Template>;
+        create: (input: T.TemplateContent & {
+            alias: string;
+        }) => Promise<T.Template>;
+        update: (id: string, input: {
+            draft: T.TemplateContent;
+            revision: number;
+        }) => Promise<T.Template>;
+        publish: (id: string, input: {
+            revision: number;
+        }) => Promise<T.Template>;
+        archive: (id: string, input: {
+            archived: boolean;
+            revision: number;
+        }) => Promise<T.Template>;
+        duplicate: (id: string, input: {
+            alias: string;
+        }) => Promise<T.Template>;
+        preview: (id: string, input?: T.TemplatePreviewInput) => Promise<{
+            subject: string;
+            html: string;
+            text: string;
+        }>;
+        test: (id: string, input: {
+            from: string;
+            to: string;
+            variables?: Record<string, T.PropertyValue>;
+        }) => Promise<T.EmailAccepted>;
+        createBroadcast: (id: string, input?: T.TemplateBroadcastInput) => Promise<T.Broadcast>;
+    };
+    emails: {
+        send: (input: T.EmailInput | T.TemplateEmailInput, options?: RequestOptions) => Promise<T.EmailAccepted>;
+        get: (id: string) => Promise<T.EmailStatus>;
+    };
+    contactProperties: {
+        list: (options?: T.ListOptions) => Promise<T.Page<T.Property>>;
+        get: (key: string) => Promise<T.Property>;
+        create: (input: T.PropertyInput) => Promise<T.Property>;
+        update: (key: string, input: {
+            property: T.PropertyInput;
+            revision: number;
+        }) => Promise<T.Property>;
+    };
+    topics: {
+        list: (options?: T.ListOptions) => Promise<T.Page<T.Topic>>;
+        get: (id: string) => Promise<T.Topic>;
+        create: (input: T.TopicInput) => Promise<T.Topic>;
+        update: (id: string, input: {
+            topic: T.TopicInput;
+            revision: number;
+        }) => Promise<T.Topic>;
+    };
+    contacts: {
+        list: (options?: T.ListOptions) => Promise<T.Page<T.Contact>>;
+        create: (input: T.ContactInput) => Promise<T.Contact>;
+        get: (email: string) => Promise<T.ContactDetails>;
+        update: (email: string, input: {
+            contact: Omit<T.Contact, "email" | "revision" | "addedAt">;
+            revision: number;
+        }) => Promise<T.Contact>;
+        subscribe: (email: string, topicId: string, input: T.SubscriptionInput) => Promise<T.Ok>;
+        unsubscribe: (email: string) => Promise<T.Ok>;
+    };
+    segments: {
+        list: (options?: T.ListOptions) => Promise<T.Page<T.Segment>>;
+        get: (id: string) => Promise<T.Segment>;
+        create: (input: T.SegmentInput) => Promise<T.Segment>;
+        update: (id: string, input: {
+            segment: T.SegmentInput;
+            revision: number;
+        }) => Promise<T.Segment>;
+        contacts: (id: string, options?: T.ListOptions) => Promise<T.Page<T.SegmentMember>>;
+        import: (id: string, input: T.ImportInput) => Promise<{
+            added: number;
+            duplicates: number;
+            total: number;
+        }>;
+        removeContact: (id: string, email: string) => Promise<T.Ok>;
+    };
+    broadcasts: {
+        list: (options?: T.ListOptions) => Promise<T.Page<T.Broadcast>>;
+        get: (id: string) => Promise<T.Broadcast>;
+        create: (input: T.BroadcastInput) => Promise<T.Broadcast>;
+        update: (id: string, input: {
+            draft: T.BroadcastInput;
+            revision: number;
+        }) => Promise<T.Broadcast>;
+        recipients: (id: string, options?: T.ListOptions) => Promise<T.Page<T.Recipient>>;
+        preview: (id: string, contact?: string) => Promise<T.Preview>;
+        test: (id: string, input: {
+            to: string;
+            previewEmail?: string;
+        }) => Promise<T.EmailAccepted>;
+        send: (id: string, input: T.SendBroadcastInput) => Promise<T.Broadcast>;
+        cancel: (id: string) => Promise<T.Broadcast>;
+        duplicate: (id: string) => Promise<T.Broadcast>;
+    };
+}

package/dist/index.js

@@ -0,0 +1,140 @@
+export class NaradaError extends Error {
+    status;
+    code;
+    requestId;
+    retryAfter;
+    constructor(message, status, code, requestId, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.retryAfter = retryAfter;
+        this.name = "NaradaError";
+    }
+}
+const path = encodeURIComponent;
+function query(options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    if (options.cursor)
+        params.set("cursor", options.cursor);
+    return params.size ? `?${params}` : "";
+}
+/** Server-side client. Requests are never retried implicitly, including timeouts. */
+export class Narada {
+    options;
+    baseUrl;
+    transport;
+    constructor(options) {
+        this.options = options;
+        const url = new URL(options.baseUrl);
+        if (!["http:", "https:"].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            throw new Error("baseUrl must be an HTTP(S) origin or path without credentials, query, or fragment");
+        if (!options.apiKey)
+            throw new Error("apiKey is required");
+        if (options.timeoutMs !== undefined &&
+            (!Number.isInteger(options.timeoutMs) || options.timeoutMs <= 0))
+            throw new Error("timeoutMs must be a positive integer");
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.transport = options.fetch ?? globalThis.fetch;
+    }
+    async request(method, endpoint, body, options = {}) {
+        const timeout = AbortSignal.timeout(this.options.timeoutMs ?? 30000);
+        const response = await this.transport(`${this.baseUrl}/api/v1${endpoint}`, {
+            method,
+            redirect: "error",
+            signal: options.signal
+                ? AbortSignal.any([timeout, options.signal])
+                : timeout,
+            headers: {
+                authorization: `Bearer ${this.options.apiKey}`,
+                accept: "application/json",
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                ...(options.idempotencyKey
+                    ? { "idempotency-key": options.idempotencyKey }
+                    : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const raw = await response.text();
+        let data;
+        try {
+            data = raw ? JSON.parse(raw) : undefined;
+        }
+        catch {
+            throw new NaradaError(`Narada returned a non-JSON response (HTTP ${response.status})`, response.status, "invalid_response", response.headers.get("x-request-id") ?? undefined);
+        }
+        if (!response.ok) {
+            const error = data;
+            const retry = response.headers.get("retry-after");
+            throw new NaradaError(typeof error?.error === "string"
+                ? error.error
+                : `Narada HTTP ${response.status}`, response.status, error?.code, error?.requestId ?? response.headers.get("x-request-id") ?? undefined, retry && /^\d+$/.test(retry) ? Number(retry) : undefined);
+        }
+        return data;
+    }
+    /** Backward-compatible alias for emails.send. */
+    send = (input, options = {}) => this.emails.send(input, options);
+    templates = {
+        list: (options) => this.request("GET", `/templates${query(options)}`),
+        get: (id) => this.request("GET", `/templates/${path(id)}`),
+        create: (input) => this.request("POST", "/templates", input),
+        update: (id, input) => this.request("PUT", `/templates/${path(id)}`, input),
+        publish: (id, input) => this.request("POST", `/templates/${path(id)}/publish`, input),
+        archive: (id, input) => this.request("POST", `/templates/${path(id)}/archive`, input),
+        duplicate: (id, input) => this.request("POST", `/templates/${path(id)}/duplicate`, input),
+        preview: (id, input = {}) => this.request("POST", `/templates/${path(id)}/preview`, input),
+        test: (id, input) => this.request("POST", `/templates/${path(id)}/test`, input),
+        createBroadcast: (id, input = {}) => this.request("POST", `/templates/${path(id)}/broadcasts`, input),
+    };
+    emails = {
+        send: (input, options = {}) => this.request("POST", "/emails", input, options),
+        get: (id) => this.request("GET", `/emails/${path(id)}`),
+    };
+    contactProperties = {
+        list: (options) => this.request("GET", `/properties${query(options)}`),
+        get: (key) => this.request("GET", `/properties/${path(key)}`),
+        create: (input) => this.request("POST", "/properties", input),
+        update: (key, input) => this.request("PUT", `/properties/${path(key)}`, input),
+    };
+    topics = {
+        list: (options) => this.request("GET", `/topics${query(options)}`),
+        get: (id) => this.request("GET", `/topics/${path(id)}`),
+        create: (input) => this.request("POST", "/topics", input),
+        update: (id, input) => this.request("PUT", `/topics/${path(id)}`, input),
+    };
+    contacts = {
+        list: (options) => this.request("GET", `/contacts${query(options)}`),
+        create: (input) => this.request("POST", "/contacts", input),
+        get: (email) => this.request("GET", `/contacts/${path(email)}`),
+        update: (email, input) => this.request("PUT", `/contacts/${path(email)}`, input),
+        subscribe: (email, topicId, input) => this.request("POST", `/contacts/${path(email)}/topics/${path(topicId)}`, input),
+        unsubscribe: (email) => this.request("POST", `/contacts/${path(email)}/unsubscribe`),
+    };
+    segments = {
+        list: (options) => this.request("GET", `/segments${query(options)}`),
+        get: (id) => this.request("GET", `/segments/${path(id)}`),
+        create: (input) => this.request("POST", "/segments", input),
+        update: (id, input) => this.request("PUT", `/segments/${path(id)}`, input),
+        contacts: (id, options) => this.request("GET", `/segments/${path(id)}/contacts${query(options)}`),
+        import: (id, input) => this.request("POST", `/segments/${path(id)}/import`, input),
+        removeContact: (id, email) => this.request("DELETE", `/segments/${path(id)}/contacts/${path(email)}`),
+    };
+    broadcasts = {
+        list: (options) => this.request("GET", `/broadcasts${query(options)}`),
+        get: (id) => this.request("GET", `/broadcasts/${path(id)}`),
+        create: (input) => this.request("POST", "/broadcasts", input),
+        update: (id, input) => this.request("PUT", `/broadcasts/${path(id)}`, input),
+        recipients: (id, options) => this.request("GET", `/broadcasts/${path(id)}/recipients${query(options)}`),
+        preview: (id, contact) => this.request("GET", `/broadcasts/${path(id)}/preview${contact ? `?contact=${path(contact)}` : ""}`),
+        test: (id, input) => this.request("POST", `/broadcasts/${path(id)}/test`, input),
+        send: (id, input) => this.request("POST", `/broadcasts/${path(id)}/send`, input),
+        cancel: (id) => this.request("POST", `/broadcasts/${path(id)}/cancel`),
+        duplicate: (id) => this.request("POST", `/broadcasts/${path(id)}/duplicate`),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+/** Public v1 contracts. No database or server-runtime dependencies. */
+export type PropertyValue = string | number | boolean;
+export interface Page<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+export interface ListOptions {
+    limit?: number;
+    cursor?: string;
+}
+export interface EmailInput {
+    from: string;
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    reply_to?: string;
+    expires_in?: number;
+}
+export interface EmailAccepted {
+    id: string;
+    replayed: boolean;
+}
+export interface EmailStatus {
+    id: string;
+    status: string;
+    created_at: string;
+    events: {
+        id: string;
+        type: string;
+        at: string;
+        recipients: string[];
+        reason?: string;
+        permanent?: boolean;
+    }[];
+}
+export interface PropertyInput {
+    key: string;
+    type: "string" | "number" | "boolean" | "date";
+    fallback?: PropertyValue;
+}
+export interface Property extends PropertyInput {
+    revision: number;
+    createdAt: string;
+}
+export interface ContactInput {
+    email: string;
+    name?: string;
+    first_name?: string;
+    last_name?: string;
+    properties?: Record<string, PropertyValue>;
+}
+export interface Contact {
+    email: string;
+    name: string;
+    first_name: string;
+    last_name: string;
+    properties: Record<string, PropertyValue>;
+    revision: number;
+    addedAt: string;
+}
+export interface TopicInput {
+    name: string;
+    description?: string;
+    visibility?: "public" | "private";
+    active?: boolean;
+}
+export interface Topic {
+    id: string;
+    name: string;
+    description: string;
+    visibility: "public" | "private";
+    active: boolean;
+    revision: number;
+    createdAt: string;
+}
+export interface ContactDetails {
+    contact: Contact;
+    topics: (Topic & {
+        subscribed: boolean;
+    })[];
+    unsubscribedAll: boolean;
+}
+export interface SegmentRule {
+    property: string;
+    operator: "equals" | "not_equals" | "contains" | "greater_than" | "less_than" | "is_set" | "is_not_set";
+    value?: PropertyValue;
+}
+export interface SegmentInput {
+    name: string;
+    kind: "manual" | "dynamic";
+    match?: "all" | "any";
+    rules?: SegmentRule[];
+}
+export interface Segment {
+    id: string;
+    name: string;
+    kind: "manual" | "dynamic";
+    match: "all" | "any";
+    rules: SegmentRule[];
+    revision: number;
+    total: number;
+    updatedAt: string;
+}
+export interface SegmentMember {
+    email: string;
+    name: string;
+    consentSource: string;
+    consentedAt: string;
+}
+export interface ImportInput {
+    csv: string;
+    consentSource: string;
+    consentConfirmed: true;
+    topicIds?: string[];
+}
+export interface BroadcastInput {
+    name: string;
+    audienceId?: string;
+    topicId?: string;
+    from?: string;
+    subject?: string;
+    text?: string;
+    html?: string;
+    organization?: string;
+    postalAddress?: string;
+    replyTo?: string;
+}
+export interface Broadcast {
+    id: string;
+    draft: BroadcastInput;
+    status: "draft" | "scheduled" | "sending" | "completed" | "cancelled";
+    revision: number;
+    total: number;
+    createdAt: string;
+    updatedAt: string;
+    scheduledAt?: number;
+}
+export interface Recipient {
+    email: string;
+    name: string;
+    messageId: string;
+    status: string;
+    error?: string;
+}
+export interface Preview {
+    subject: string;
+    html: string;
+    text?: string;
+    eligible: number;
+    total: number;
+    excluded: number;
+    previewEmail?: string;
+}
+export interface SendBroadcastInput {
+    revision: number;
+    confirmed: true;
+    scheduledAt?: number;
+}
+export interface SubscriptionInput {
+    subscribed: boolean;
+    source: string;
+    confirmed: true;
+}
+export interface Ok {
+    ok: true;
+}
+export interface TemplateVariable {
+    key: string;
+    type?: "string" | "number" | "boolean" | "url";
+    fallback?: PropertyValue;
+}
+export interface TemplateContent {
+    name: string;
+    kind?: "transactional" | "broadcast";
+    subject?: string;
+    html?: string;
+    text?: string;
+    variables?: TemplateVariable[];
+}
+export interface Template {
+    id: string;
+    alias: string;
+    draft: TemplateContent;
+    revision: number;
+    publishedVersion?: number;
+    archived: boolean;
+    status: "draft" | "published" | "archived";
+    hasUnpublishedChanges: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TemplateEmailInput {
+    from: string;
+    to: string | string[];
+    reply_to?: string;
+    expires_in?: number;
+    template: {
+        id: string;
+        version?: number;
+        variables?: Record<string, PropertyValue>;
+    };
+}
+export interface TemplatePreviewInput {
+    variables?: Record<string, PropertyValue>;
+    version?: number;
+}
+export interface TemplateBroadcastInput extends TemplatePreviewInput {
+    name?: string;
+    audienceId?: string;
+    topicId?: string;
+    from?: string;
+    organization?: string;
+    postalAddress?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@durgadigital/narada",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Typed server-side SDK for a self-hosted Narada API",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Durga-Digital/narada.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}