@vorluno/niiko-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Vorluno
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,103 @@
+# @vorluno/niiko-sdk
+
+The TypeScript client for the niiko actions API. One typed method per action, three outcomes, zero dependencies.
+
+[![npm](https://img.shields.io/npm/v/%40vorluno%2Fniiko-sdk?style=flat-square&color=0969da)](https://www.npmjs.com/package/@vorluno/niiko-sdk) [![node](https://img.shields.io/badge/node-%3E%3D18-2C6440?style=flat-square)](https://nodejs.org) ![dependencies](https://img.shields.io/badge/dependencies-0-2C6440?style=flat-square) ![license](https://img.shields.io/badge/license-Apache--2.0-0969da?style=flat-square) [![generated](https://img.shields.io/badge/generated_from_plan-6c3240a7b22d-555?style=flat-square)](https://developers.niiko.org)
+
+**A client that knows the actions it was written for is stale the day a new one opens.** This one is
+generated from the niiko action manifest, in the same run as the Python client and the reference (plan `6c3240a7b22d`),
+so an action that opens on the server appears here as a typed method at once — and nothing in this repository
+is edited by hand.
+
+## Install
+
+```bash
+npm install @vorluno/niiko-sdk
+```
+
+Zero runtime dependencies. A client that drags an HTTP library along forces whoever installs it to resolve a
+version conflict just to send a POST.
+
+## Use
+
+```ts
+import { Niiko } from "@vorluno/niiko-sdk";
+
+const niiko = new Niiko({ apiKey: process.env.NIIKO_API_KEY! });
+
+// The second argument is the idempotency key: keep it if you retry.
+const r = await niiko.createLead({
+  submissionId: "01890a5d-ac96-774b-bcce-b302099a8057",
+  source: "web_form",
+}, crypto.randomUUID());
+
+if (r.status === "done") console.log(r.output);
+else if (r.status === "refused") console.error(r.reason, r.detail?.message);
+else console.log("waiting for a human signature", r.proposalId);
+```
+
+## Three outcomes, not two
+
+| `status` | Meaning |
+|---|---|
+| `done` | Done. Carries the `output`. |
+| `pending_approval` | **Waits for a human signature** and may complete hours later. A webhook tells you when it resolves. |
+| `refused` | Not done, and `reason` says why. `detail.message`, when present, says what to do. |
+
+A two-outcome contract forces the third one to disguise itself as another, and the disguised one is always
+the one that takes longest to understand. Branch once on `status`; a refusal is a state, not an exception.
+
+> [!NOTE]
+> Send an idempotency key with every request. A timeout retry with the same key **does not execute again**: it
+> answers `refused` with `reason: "duplicate"` and what happened the first time. Without one, a retry is a new
+> request. The protection lasts 24 hours.
+
+> [!IMPORTANT]
+> Each action needs **two** permissions: a key with that action's scope, **and** the workspace owner having
+> switched it on (Administration → Permissions). Holding the key is not enough — they are two decisions made
+> by different people.
+
+## The actions today (13)
+
+| Action | Method | What it does |
+|---|---|---|
+| `miira.lead_create` | `createLead` | Creates a new lead in the workspace CRM from its contact details. If a matching one already exists it is not duplicated: the reply is `ambiguous` with the candidates. |
+| `crm.call_logged` | `loggedCall` | Logs what was discussed in a call on a client's record, naming the client; optionally creates the follow-up with its date. Reads nothing and calls no one. |
+| `crm.owner_assigned` | `assignedOwner` | Changes who owns a client, naming the client and the team member (by name or email). If either is ambiguous it refuses with the list. |
+| `crm.stage_moved` | `movedStage` | Moves a client's open deal to another pipeline stage, naming the client and the stage. Creates no deals: with no open deal it refuses, and with several it refuses with the list. |
+| `kiipu.invoice_proposed` | `proposedInvoice` | Prepares an invoice as a DRAFT for a client named by name, with its lines and taxes. Does NOT issue it, does NOT number it and does NOT count as debt: a person reviews and issues it in Kiipu. Does not create the client if it does not exist. |
+| `crm.task_created` | `createdTask` | Creates a reminder (a task with date and time) on a client named by name. Does not log a call: that is crm.call_logged. Does not create the client if it does not exist. |
+| `crm.deal_created` | `createdDeal` | Opens a new deal in the pipeline for a client named by name, with a title, an optional value in USD, an optional stage (by name; without it, the first one) and an optional owner. Does not check for other open deals: it returns how many remain so a duplicate is visible. Does not win or lose it: that is crm.stage_moved. |
+| `crm.note_added` | `addedNote` | Saves a note on a client's record, naming the client: something to know next time, with no call and no date. For a call use crm.call_logged; for a dated reminder, crm.task_created. |
+| `crm.contact_added` | `addedContact` | Adds a person (name, and optionally email, phone and role) to a client's record, naming the client. Does not make them the primary contact and does not create the client. If someone with that email or phone already existed, the reply says so but does not block it. |
+| `miira.broadcast_quoted` | `quotedBroadcast` | Quotes sending the SAME WhatsApp message to several clients named by name (up to 50). Sends NOTHING: per client, it says whether the text goes as-is (24-hour window open, free), whether an approved template is needed and what it costs, or why that client cannot be messaged. Returns a signed quote valid for 15 minutes; to send, call miira.broadcast_sent with it. Show the quote to the person first. |
+| `miira.broadcast_sent` | `sentBroadcast` | Sends the WhatsApp broadcast quoted by miira.broadcast_quoted, exactly to whom and how the quote said. If anything changed (window, consent, rate) it refuses with a new quote to confirm again. Costs money when templates are involved: do not call it without the person having seen the cost. |
+| `kiipu.draft_voided` | `voidedDraft` | Voids a DRAFT invoice (one created with kiipu.invoice_proposed and not yet issued), by its id or by the client's name when it is their only draft. Does not void issued invoices: that is for a person in Kiipu. |
+| `kiipu.payment_reported` | `reportedPayment` | Leaves in the Kiipu approval queue the notice that a client (by name) paid a given amount of an open invoice. Does NOT apply the payment and touches no balances: a person checks it against the bank and applies it. If the client has several open invoices the number must be given. |
+
+## What this client does not do
+
+| Not included | Why |
+|---|---|
+| **Validate your input** | It could — the schema is published — and that would be worse: a client that validates can disagree with the server, and the likely direction of the error is the dangerous one (approving what the server will reject). The server validates, and its refusal travels with a name. What this client gives you is the **shape**, in your editor, before sending anything. |
+| **Read anything** | This API exposes verbs, not rows. There is nothing to list or paginate. |
+| **Retry on its own** | A retry is a decision about your idempotency key. The client keeps it explicit. |
+
+## Support
+
+| | |
+|---|---|
+| **Versioning** | Semantic. Every visible change is in the [changelog](https://developers.niiko.org/#changelog) of the API reference. |
+| **Regeneration** | This repository is generated from the niiko action manifest. When an action opens or a contract changes, a new version is published — nothing here is edited by hand. |
+| **Issues** | [vorluno/niiko-sdk-typescript/issues](https://github.com/vorluno/niiko-sdk-typescript/issues) — a fault of the API itself starts at [developers.niiko.org](https://developers.niiko.org). |
+| **Security** | `security@vorluno.dev` — first response within 48 hours, patch or plan within 7 days. |
+
+## Related
+
+- **[niiko (Python)](https://github.com/vorluno/niiko-sdk-python)** — the Python client, same plan.
+- **[niiko-cli](https://github.com/vorluno/niiko-cli)** — the same actions from the terminal, with the outcome in the exit code.
+- **[n8n-nodes-niiko](https://github.com/vorluno/n8n-nodes-niiko)** — the same actions as an n8n node.
+- **[niiko-mcp-server](https://github.com/vorluno/niiko-mcp-server)** — the same actions as MCP tools, for Claude and other AI clients.
+- **[developers.niiko.org](https://developers.niiko.org)** — the API reference this is generated alongside.
+
+<sub>Built and maintained by <a href="https://vorluno.dev">Vorluno</a>, a software studio in Panama, and generated from <a href="https://niiko.org">niiko</a>'s production action manifest — the same one the server enforces. Apache 2.0.</sub>

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+/** The three outcomes. Branch once on `status` and you know where you are. */
+export type Result<T> = {
+    status: "done";
+    output: T;
+    idempotencyKey: string;
+}
+/** Waits for a human signature and may complete hours later. You get notified by webhook. */
+ | {
+    status: "pending_approval";
+    proposalId: string | null;
+    autonomy: string;
+}
+/** Not done. `reason` is a named reason and `detail.message`, when present, says what to do. */
+ | {
+    status: "refused";
+    reason: string;
+    detail?: Record<string, unknown>;
+};
+export declare class NiikoError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+export interface CreateLeadInput {
+    submissionId: string;
+    source: "web_form" | "referral" | "api" | "import" | "event" | "other";
+    name?: string;
+    email?: string;
+    phone?: string;
+    fields?: Record<string, unknown>;
+    consent?: {
+        email: boolean;
+        whatsapp: boolean;
+        source: "api" | "web_form" | "verbal" | "llamada" | "visita" | "imported";
+    };
+}
+export interface CreateLeadOutput {
+    outcome: "created" | "existing" | "ambiguous" | "rejected";
+    clientId: string | null;
+    reason: "honeypot" | "invalid_email" | "disposable_email" | "invalid_identity" | null;
+}
+/** The reasons `miira.lead_create` declares. One outside this list is a server fault, not a state. */
+export type CreateLeadReason = "honeypot" | "invalid_email" | "disposable_email" | "invalid_identity";
+export interface LoggedCallInput {
+    client: string;
+    summary: string;
+    followUp?: {
+        what: string;
+        dueAt: string;
+    };
+}
+export interface LoggedCallOutput {
+    clientId: string;
+    clientName: string;
+    activityId: string;
+    followUpId: string | null;
+}
+/** The reasons `crm.call_logged` declares. One outside this list is a server fault, not a state. */
+export type LoggedCallReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+export interface AssignedOwnerInput {
+    client: string;
+    owner: string;
+}
+export interface AssignedOwnerOutput {
+    clientId: string;
+    clientName: string;
+    ownerUserId: string;
+    ownerName: string;
+}
+/** The reasons `crm.owner_assigned` declares. One outside this list is a server fault, not a state. */
+export type AssignedOwnerReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "persona_no_encontrada" | "persona_ambigua" | "sin_permiso";
+export interface MovedStageInput {
+    client: string;
+    stage: string;
+    lostReason?: string;
+}
+export interface MovedStageOutput {
+    dealId: string;
+    clientId: string;
+    clientName: string;
+    stageName: string;
+    won: boolean;
+    firstWon: boolean;
+}
+/** The reasons `crm.stage_moved` declares. One outside this list is a server fault, not a state. */
+export type MovedStageReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_negocio_abierto" | "varios_negocios" | "etapa_no_encontrada" | "negocio_cerrado" | "ya_en_esa_etapa" | "sin_permiso";
+export interface ProposedInvoiceInput {
+    client: string;
+    lines: {
+        concept: string;
+        quantity: string;
+        unitPriceUsd: string;
+        tax: "exempt" | "itbms_7" | "itbms_10" | "itbms_15";
+    }[];
+    dueAt?: string;
+    series?: string;
+}
+export interface ProposedInvoiceOutput {
+    invoiceId: string;
+    clientId: string;
+    clientName: string;
+    status: "draft";
+    subtotalUsd: string;
+    taxUsd: string;
+    totalUsd: string;
+    dueAt: string;
+    series: string;
+    issueAt: "/kiipu/facturas";
+}
+/** The reasons `kiipu.invoice_proposed` declares. One outside this list is a server fault, not a state. */
+export type ProposedInvoiceReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+export interface CreatedTaskInput {
+    client: string;
+    what: string;
+    dueAt: string;
+}
+export interface CreatedTaskOutput {
+    clientId: string;
+    clientName: string;
+    taskId: string;
+    dueAt: string;
+}
+/** The reasons `crm.task_created` declares. One outside this list is a server fault, not a state. */
+export type CreatedTaskReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+export interface CreatedDealInput {
+    client: string;
+    title: string;
+    valueUsd?: string;
+    stage?: string;
+    owner?: string;
+}
+export interface CreatedDealOutput {
+    dealId: string;
+    clientId: string;
+    clientName: string;
+    title: string;
+    valueUsd: string | null;
+    stageName: string;
+    ownerName: string | null;
+    openDeals: number;
+}
+/** The reasons `crm.deal_created` declares. One outside this list is a server fault, not a state. */
+export type CreatedDealReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "etapa_no_encontrada" | "etapa_cerrada" | "persona_no_encontrada" | "persona_ambigua" | "sin_permiso";
+export interface AddedNoteInput {
+    client: string;
+    note: string;
+}
+export interface AddedNoteOutput {
+    clientId: string;
+    clientName: string;
+    noteId: string;
+}
+/** The reasons `crm.note_added` declares. One outside this list is a server fault, not a state. */
+export type AddedNoteReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+export interface AddedContactInput {
+    client: string;
+    name: string;
+    email?: string;
+    phone?: string;
+    role?: string;
+}
+export interface AddedContactOutput {
+    clientId: string;
+    clientName: string;
+    contactId: string;
+    possibleDuplicate: boolean;
+}
+/** The reasons `crm.contact_added` declares. One outside this list is a server fault, not a state. */
+export type AddedContactReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+export interface QuotedBroadcastInput {
+    clients: string[];
+    message: string;
+    template?: string;
+    templateValues?: string[];
+}
+export interface QuotedBroadcastOutput {
+    rows: {
+        client: string;
+        clientId: string | null;
+        clientName: string | null;
+        outcome: "free_text" | "template" | "needs_template" | "no_phone" | "suppressed" | "consent_revoked" | "no_marketing_consent" | "quiet_hours" | "not_found" | "ambiguous" | "too_many";
+        costUsd: string | null;
+        candidates: string[];
+    }[];
+    totals: {
+        freeText: number;
+        template: number;
+        skipped: number;
+        costUsd: string;
+    };
+    quote: string | null;
+    expiresAt: string | null;
+}
+/** The reasons `miira.broadcast_quoted` declares. One outside this list is a server fault, not a state. */
+export type QuotedBroadcastReason = "plantilla_invalida" | "tarifas_vencidas" | "sin_permiso";
+export interface SentBroadcastInput {
+    quote: string;
+}
+export interface SentBroadcastOutput {
+    queued: {
+        clientId: string;
+        clientName: string;
+        mode: "free_text" | "template";
+        outboxId: string;
+    }[];
+    costUsd: string;
+}
+/** The reasons `miira.broadcast_sent` declares. One outside this list is a server fault, not a state. */
+export type SentBroadcastReason = "presupuesto_invalido" | "presupuesto_vencido" | "presupuesto_cambiado" | "plantilla_invalida" | "tarifas_vencidas" | "sin_permiso";
+export interface VoidedDraftInput {
+    invoiceId?: string;
+    client?: string;
+}
+export interface VoidedDraftOutput {
+    invoiceId: string;
+    clientId: string;
+    clientName: string;
+    totalUsd: string;
+    status: "void";
+}
+/** The reasons `kiipu.draft_voided` declares. One outside this list is a server fault, not a state. */
+export type VoidedDraftReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "borrador_no_encontrado" | "varios_borradores" | "no_es_borrador" | "sin_permiso";
+export interface ReportedPaymentInput {
+    client: string;
+    amountUsd: string;
+    invoice?: string;
+}
+export interface ReportedPaymentOutput {
+    submissionId: string;
+    clientId: string;
+    clientName: string;
+    invoiceId: string;
+    invoiceNumber: string;
+    outstandingUsd: string;
+    declaredUsd: string;
+    status: "received";
+    reviewAt: "/kiipu/aprobaciones";
+}
+/** The reasons `kiipu.payment_reported` declares. One outside this list is a server fault, not a state. */
+export type ReportedPaymentReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_factura_abierta" | "varias_facturas" | "factura_no_encontrada" | "sin_permiso";
+export interface NiikoOptions {
+    /** The workspace API key. Shown ONCE, when created in Settings. */
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export declare class Niiko {
+    #private;
+    constructor(o: NiikoOptions);
+    /**
+     * Creates a new lead in the workspace CRM from its contact details. If a matching one already exists it is not duplicated: the reply is `ambiguous` with the candidates.
+     *
+     * `miira.lead_create` v1 — scope `miira.lead_create@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    createLead(input: CreateLeadInput, idempotencyKey?: string): Promise<Result<CreateLeadOutput>>;
+    /**
+     * Logs what was discussed in a call on a client's record, naming the client; optionally creates the follow-up with its date. Reads nothing and calls no one.
+     *
+     * `crm.call_logged` v1 — scope `crm.call_logged@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    loggedCall(input: LoggedCallInput, idempotencyKey?: string): Promise<Result<LoggedCallOutput>>;
+    /**
+     * Changes who owns a client, naming the client and the team member (by name or email). If either is ambiguous it refuses with the list.
+     *
+     * `crm.owner_assigned` v1 — scope `crm.owner_assigned@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    assignedOwner(input: AssignedOwnerInput, idempotencyKey?: string): Promise<Result<AssignedOwnerOutput>>;
+    /**
+     * Moves a client's open deal to another pipeline stage, naming the client and the stage. Creates no deals: with no open deal it refuses, and with several it refuses with the list.
+     *
+     * `crm.stage_moved` v1 — scope `crm.stage_moved@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    movedStage(input: MovedStageInput, idempotencyKey?: string): Promise<Result<MovedStageOutput>>;
+    /**
+     * Prepares an invoice as a DRAFT for a client named by name, with its lines and taxes. Does NOT issue it, does NOT number it and does NOT count as debt: a person reviews and issues it in Kiipu. Does not create the client if it does not exist.
+     *
+     * `kiipu.invoice_proposed` v1 — scope `kiipu.invoice_proposed@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    proposedInvoice(input: ProposedInvoiceInput, idempotencyKey?: string): Promise<Result<ProposedInvoiceOutput>>;
+    /**
+     * Creates a reminder (a task with date and time) on a client named by name. Does not log a call: that is crm.call_logged. Does not create the client if it does not exist.
+     *
+     * `crm.task_created` v1 — scope `crm.task_created@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    createdTask(input: CreatedTaskInput, idempotencyKey?: string): Promise<Result<CreatedTaskOutput>>;
+    /**
+     * Opens a new deal in the pipeline for a client named by name, with a title, an optional value in USD, an optional stage (by name; without it, the first one) and an optional owner. Does not check for other open deals: it returns how many remain so a duplicate is visible. Does not win or lose it: that is crm.stage_moved.
+     *
+     * `crm.deal_created` v1 — scope `crm.deal_created@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    createdDeal(input: CreatedDealInput, idempotencyKey?: string): Promise<Result<CreatedDealOutput>>;
+    /**
+     * Saves a note on a client's record, naming the client: something to know next time, with no call and no date. For a call use crm.call_logged; for a dated reminder, crm.task_created.
+     *
+     * `crm.note_added` v1 — scope `crm.note_added@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    addedNote(input: AddedNoteInput, idempotencyKey?: string): Promise<Result<AddedNoteOutput>>;
+    /**
+     * Adds a person (name, and optionally email, phone and role) to a client's record, naming the client. Does not make them the primary contact and does not create the client. If someone with that email or phone already existed, the reply says so but does not block it.
+     *
+     * `crm.contact_added` v1 — scope `crm.contact_added@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    addedContact(input: AddedContactInput, idempotencyKey?: string): Promise<Result<AddedContactOutput>>;
+    /**
+     * Quotes sending the SAME WhatsApp message to several clients named by name (up to 50). Sends NOTHING: per client, it says whether the text goes as-is (24-hour window open, free), whether an approved template is needed and what it costs, or why that client cannot be messaged. Returns a signed quote valid for 15 minutes; to send, call miira.broadcast_sent with it. Show the quote to the person first.
+     *
+     * `miira.broadcast_quoted` v1 — scope `miira.broadcast_quoted@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    quotedBroadcast(input: QuotedBroadcastInput, idempotencyKey?: string): Promise<Result<QuotedBroadcastOutput>>;
+    /**
+     * Sends the WhatsApp broadcast quoted by miira.broadcast_quoted, exactly to whom and how the quote said. If anything changed (window, consent, rate) it refuses with a new quote to confirm again. Costs money when templates are involved: do not call it without the person having seen the cost.
+     *
+     * `miira.broadcast_sent` v1 — scope `miira.broadcast_sent@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    sentBroadcast(input: SentBroadcastInput, idempotencyKey?: string): Promise<Result<SentBroadcastOutput>>;
+    /**
+     * Voids a DRAFT invoice (one created with kiipu.invoice_proposed and not yet issued), by its id or by the client's name when it is their only draft. Does not void issued invoices: that is for a person in Kiipu.
+     *
+     * `kiipu.draft_voided` v1 — scope `kiipu.draft_voided@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    voidedDraft(input: VoidedDraftInput, idempotencyKey?: string): Promise<Result<VoidedDraftOutput>>;
+    /**
+     * Leaves in the Kiipu approval queue the notice that a client (by name) paid a given amount of an open invoice. Does NOT apply the payment and touches no balances: a person checks it against the bank and applies it. If the client has several open invoices the number must be given.
+     *
+     * `kiipu.payment_reported` v1 — scope `kiipu.payment_reported@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    reportedPayment(input: ReportedPaymentInput, idempotencyKey?: string): Promise<Result<ReportedPaymentOutput>>;
+}

package/dist/index.js

@@ -0,0 +1,174 @@
+// GENERATED from the niiko action manifest — plan `6c3240a7b22d`. Do not edit by hand.
+//
+// Every method here exists because an action is DECLARED public. If the server answers `not_exposed`,
+// this copy of the SDK is newer than the deployment — not that you got the name wrong.
+export class NiikoError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`niiko: the server answered ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = "NiikoError";
+    }
+}
+export class Niiko {
+    #apiKey;
+    #baseUrl;
+    #fetch;
+    constructor(o) {
+        if (!o.apiKey)
+            throw new Error("niiko: apiKey is required");
+        this.#apiKey = o.apiKey;
+        this.#baseUrl = (o.baseUrl ?? "https://niiko.org").replace(/\/+$/, "");
+        this.#fetch = o.fetch ?? fetch;
+    }
+    async #exercise(action, body, idempotencyKey) {
+        const r = await this.#fetch(`${this.#baseUrl}/api/v1/actions/${action}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.#apiKey}`,
+                "content-type": "application/json",
+                // Send it WHENEVER you can: a timeout retry with the same key does not execute again.
+                ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+        const json = await r.json().catch(() => null);
+        // A refusal is NOT an exception: it is a product state, and the caller must be able to branch on it.
+        // What does throw is what cannot be read — there is no decision to make there.
+        if (json && typeof json === "object" && "status" in json)
+            return json;
+        throw new NiikoError(r.status, json);
+    }
+    /**
+     * Creates a new lead in the workspace CRM from its contact details. If a matching one already exists it is not duplicated: the reply is `ambiguous` with the candidates.
+     *
+     * `miira.lead_create` v1 — scope `miira.lead_create@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async createLead(input, idempotencyKey) {
+        return this.#exercise("miira.lead_create", input, idempotencyKey);
+    }
+    /**
+     * Logs what was discussed in a call on a client's record, naming the client; optionally creates the follow-up with its date. Reads nothing and calls no one.
+     *
+     * `crm.call_logged` v1 — scope `crm.call_logged@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async loggedCall(input, idempotencyKey) {
+        return this.#exercise("crm.call_logged", input, idempotencyKey);
+    }
+    /**
+     * Changes who owns a client, naming the client and the team member (by name or email). If either is ambiguous it refuses with the list.
+     *
+     * `crm.owner_assigned` v1 — scope `crm.owner_assigned@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async assignedOwner(input, idempotencyKey) {
+        return this.#exercise("crm.owner_assigned", input, idempotencyKey);
+    }
+    /**
+     * Moves a client's open deal to another pipeline stage, naming the client and the stage. Creates no deals: with no open deal it refuses, and with several it refuses with the list.
+     *
+     * `crm.stage_moved` v1 — scope `crm.stage_moved@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async movedStage(input, idempotencyKey) {
+        return this.#exercise("crm.stage_moved", input, idempotencyKey);
+    }
+    /**
+     * Prepares an invoice as a DRAFT for a client named by name, with its lines and taxes. Does NOT issue it, does NOT number it and does NOT count as debt: a person reviews and issues it in Kiipu. Does not create the client if it does not exist.
+     *
+     * `kiipu.invoice_proposed` v1 — scope `kiipu.invoice_proposed@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async proposedInvoice(input, idempotencyKey) {
+        return this.#exercise("kiipu.invoice_proposed", input, idempotencyKey);
+    }
+    /**
+     * Creates a reminder (a task with date and time) on a client named by name. Does not log a call: that is crm.call_logged. Does not create the client if it does not exist.
+     *
+     * `crm.task_created` v1 — scope `crm.task_created@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async createdTask(input, idempotencyKey) {
+        return this.#exercise("crm.task_created", input, idempotencyKey);
+    }
+    /**
+     * Opens a new deal in the pipeline for a client named by name, with a title, an optional value in USD, an optional stage (by name; without it, the first one) and an optional owner. Does not check for other open deals: it returns how many remain so a duplicate is visible. Does not win or lose it: that is crm.stage_moved.
+     *
+     * `crm.deal_created` v1 — scope `crm.deal_created@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async createdDeal(input, idempotencyKey) {
+        return this.#exercise("crm.deal_created", input, idempotencyKey);
+    }
+    /**
+     * Saves a note on a client's record, naming the client: something to know next time, with no call and no date. For a call use crm.call_logged; for a dated reminder, crm.task_created.
+     *
+     * `crm.note_added` v1 — scope `crm.note_added@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async addedNote(input, idempotencyKey) {
+        return this.#exercise("crm.note_added", input, idempotencyKey);
+    }
+    /**
+     * Adds a person (name, and optionally email, phone and role) to a client's record, naming the client. Does not make them the primary contact and does not create the client. If someone with that email or phone already existed, the reply says so but does not block it.
+     *
+     * `crm.contact_added` v1 — scope `crm.contact_added@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async addedContact(input, idempotencyKey) {
+        return this.#exercise("crm.contact_added", input, idempotencyKey);
+    }
+    /**
+     * Quotes sending the SAME WhatsApp message to several clients named by name (up to 50). Sends NOTHING: per client, it says whether the text goes as-is (24-hour window open, free), whether an approved template is needed and what it costs, or why that client cannot be messaged. Returns a signed quote valid for 15 minutes; to send, call miira.broadcast_sent with it. Show the quote to the person first.
+     *
+     * `miira.broadcast_quoted` v1 — scope `miira.broadcast_quoted@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async quotedBroadcast(input, idempotencyKey) {
+        return this.#exercise("miira.broadcast_quoted", input, idempotencyKey);
+    }
+    /**
+     * Sends the WhatsApp broadcast quoted by miira.broadcast_quoted, exactly to whom and how the quote said. If anything changed (window, consent, rate) it refuses with a new quote to confirm again. Costs money when templates are involved: do not call it without the person having seen the cost.
+     *
+     * `miira.broadcast_sent` v1 — scope `miira.broadcast_sent@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async sentBroadcast(input, idempotencyKey) {
+        return this.#exercise("miira.broadcast_sent", input, idempotencyKey);
+    }
+    /**
+     * Voids a DRAFT invoice (one created with kiipu.invoice_proposed and not yet issued), by its id or by the client's name when it is their only draft. Does not void issued invoices: that is for a person in Kiipu.
+     *
+     * `kiipu.draft_voided` v1 — scope `kiipu.draft_voided@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async voidedDraft(input, idempotencyKey) {
+        return this.#exercise("kiipu.draft_voided", input, idempotencyKey);
+    }
+    /**
+     * Leaves in the Kiipu approval queue the notice that a client (by name) paid a given amount of an open invoice. Does NOT apply the payment and touches no balances: a person checks it against the bank and applies it. If the client has several open invoices the number must be given.
+     *
+     * `kiipu.payment_reported` v1 — scope `kiipu.payment_reported@1`.
+     *
+     * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+     */
+    async reportedPayment(input, idempotencyKey) {
+        return this.#exercise("kiipu.payment_reported", input, idempotencyKey);
+    }
+}

package/index.ts

@@ -0,0 +1,428 @@
+// GENERATED from the niiko action manifest — plan `6c3240a7b22d`. Do not edit by hand.
+//
+// Every method here exists because an action is DECLARED public. If the server answers `not_exposed`,
+// this copy of the SDK is newer than the deployment — not that you got the name wrong.
+
+/** The three outcomes. Branch once on `status` and you know where you are. */
+export type Result<T> =
+  | { status: "done"; output: T; idempotencyKey: string }
+  /** Waits for a human signature and may complete hours later. You get notified by webhook. */
+  | { status: "pending_approval"; proposalId: string | null; autonomy: string }
+  /** Not done. `reason` is a named reason and `detail.message`, when present, says what to do. */
+  | { status: "refused"; reason: string; detail?: Record<string, unknown> };
+
+export class NiikoError extends Error {
+  constructor(readonly status: number, readonly body: unknown) {
+    super(`niiko: the server answered ${status}`);
+    this.name = "NiikoError";
+  }
+}
+
+export interface CreateLeadInput {
+  submissionId: string;
+  source: "web_form" | "referral" | "api" | "import" | "event" | "other";
+  name?: string;
+  email?: string;
+  phone?: string;
+  fields?: Record<string, unknown>;
+  consent?: { email: boolean; whatsapp: boolean; source: "api" | "web_form" | "verbal" | "llamada" | "visita" | "imported" };
+}
+
+export interface CreateLeadOutput {
+  outcome: "created" | "existing" | "ambiguous" | "rejected";
+  clientId: string | null;
+  reason: "honeypot" | "invalid_email" | "disposable_email" | "invalid_identity" | null;
+}
+
+/** The reasons `miira.lead_create` declares. One outside this list is a server fault, not a state. */
+export type CreateLeadReason = "honeypot" | "invalid_email" | "disposable_email" | "invalid_identity";
+
+export interface LoggedCallInput {
+  client: string;
+  summary: string;
+  followUp?: { what: string; dueAt: string };
+}
+
+export interface LoggedCallOutput {
+  clientId: string;
+  clientName: string;
+  activityId: string;
+  followUpId: string | null;
+}
+
+/** The reasons `crm.call_logged` declares. One outside this list is a server fault, not a state. */
+export type LoggedCallReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+
+export interface AssignedOwnerInput {
+  client: string;
+  owner: string;
+}
+
+export interface AssignedOwnerOutput {
+  clientId: string;
+  clientName: string;
+  ownerUserId: string;
+  ownerName: string;
+}
+
+/** The reasons `crm.owner_assigned` declares. One outside this list is a server fault, not a state. */
+export type AssignedOwnerReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "persona_no_encontrada" | "persona_ambigua" | "sin_permiso";
+
+export interface MovedStageInput {
+  client: string;
+  stage: string;
+  lostReason?: string;
+}
+
+export interface MovedStageOutput {
+  dealId: string;
+  clientId: string;
+  clientName: string;
+  stageName: string;
+  won: boolean;
+  firstWon: boolean;
+}
+
+/** The reasons `crm.stage_moved` declares. One outside this list is a server fault, not a state. */
+export type MovedStageReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_negocio_abierto" | "varios_negocios" | "etapa_no_encontrada" | "negocio_cerrado" | "ya_en_esa_etapa" | "sin_permiso";
+
+export interface ProposedInvoiceInput {
+  client: string;
+  lines: { concept: string; quantity: string; unitPriceUsd: string; tax: "exempt" | "itbms_7" | "itbms_10" | "itbms_15" }[];
+  dueAt?: string;
+  series?: string;
+}
+
+export interface ProposedInvoiceOutput {
+  invoiceId: string;
+  clientId: string;
+  clientName: string;
+  status: "draft";
+  subtotalUsd: string;
+  taxUsd: string;
+  totalUsd: string;
+  dueAt: string;
+  series: string;
+  issueAt: "/kiipu/facturas";
+}
+
+/** The reasons `kiipu.invoice_proposed` declares. One outside this list is a server fault, not a state. */
+export type ProposedInvoiceReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+
+export interface CreatedTaskInput {
+  client: string;
+  what: string;
+  dueAt: string;
+}
+
+export interface CreatedTaskOutput {
+  clientId: string;
+  clientName: string;
+  taskId: string;
+  dueAt: string;
+}
+
+/** The reasons `crm.task_created` declares. One outside this list is a server fault, not a state. */
+export type CreatedTaskReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+
+export interface CreatedDealInput {
+  client: string;
+  title: string;
+  valueUsd?: string;
+  stage?: string;
+  owner?: string;
+}
+
+export interface CreatedDealOutput {
+  dealId: string;
+  clientId: string;
+  clientName: string;
+  title: string;
+  valueUsd: string | null;
+  stageName: string;
+  ownerName: string | null;
+  openDeals: number;
+}
+
+/** The reasons `crm.deal_created` declares. One outside this list is a server fault, not a state. */
+export type CreatedDealReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "etapa_no_encontrada" | "etapa_cerrada" | "persona_no_encontrada" | "persona_ambigua" | "sin_permiso";
+
+export interface AddedNoteInput {
+  client: string;
+  note: string;
+}
+
+export interface AddedNoteOutput {
+  clientId: string;
+  clientName: string;
+  noteId: string;
+}
+
+/** The reasons `crm.note_added` declares. One outside this list is a server fault, not a state. */
+export type AddedNoteReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+
+export interface AddedContactInput {
+  client: string;
+  name: string;
+  email?: string;
+  phone?: string;
+  role?: string;
+}
+
+export interface AddedContactOutput {
+  clientId: string;
+  clientName: string;
+  contactId: string;
+  possibleDuplicate: boolean;
+}
+
+/** The reasons `crm.contact_added` declares. One outside this list is a server fault, not a state. */
+export type AddedContactReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_permiso";
+
+export interface QuotedBroadcastInput {
+  clients: string[];
+  message: string;
+  template?: string;
+  templateValues?: string[];
+}
+
+export interface QuotedBroadcastOutput {
+  rows: { client: string; clientId: string | null; clientName: string | null; outcome: "free_text" | "template" | "needs_template" | "no_phone" | "suppressed" | "consent_revoked" | "no_marketing_consent" | "quiet_hours" | "not_found" | "ambiguous" | "too_many"; costUsd: string | null; candidates: string[] }[];
+  totals: { freeText: number; template: number; skipped: number; costUsd: string };
+  quote: string | null;
+  expiresAt: string | null;
+}
+
+/** The reasons `miira.broadcast_quoted` declares. One outside this list is a server fault, not a state. */
+export type QuotedBroadcastReason = "plantilla_invalida" | "tarifas_vencidas" | "sin_permiso";
+
+export interface SentBroadcastInput {
+  quote: string;
+}
+
+export interface SentBroadcastOutput {
+  queued: { clientId: string; clientName: string; mode: "free_text" | "template"; outboxId: string }[];
+  costUsd: string;
+}
+
+/** The reasons `miira.broadcast_sent` declares. One outside this list is a server fault, not a state. */
+export type SentBroadcastReason = "presupuesto_invalido" | "presupuesto_vencido" | "presupuesto_cambiado" | "plantilla_invalida" | "tarifas_vencidas" | "sin_permiso";
+
+export interface VoidedDraftInput {
+  invoiceId?: string;
+  client?: string;
+}
+
+export interface VoidedDraftOutput {
+  invoiceId: string;
+  clientId: string;
+  clientName: string;
+  totalUsd: string;
+  status: "void";
+}
+
+/** The reasons `kiipu.draft_voided` declares. One outside this list is a server fault, not a state. */
+export type VoidedDraftReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "borrador_no_encontrado" | "varios_borradores" | "no_es_borrador" | "sin_permiso";
+
+export interface ReportedPaymentInput {
+  client: string;
+  amountUsd: string;
+  invoice?: string;
+}
+
+export interface ReportedPaymentOutput {
+  submissionId: string;
+  clientId: string;
+  clientName: string;
+  invoiceId: string;
+  invoiceNumber: string;
+  outstandingUsd: string;
+  declaredUsd: string;
+  status: "received";
+  reviewAt: "/kiipu/aprobaciones";
+}
+
+/** The reasons `kiipu.payment_reported` declares. One outside this list is a server fault, not a state. */
+export type ReportedPaymentReason = "cliente_no_encontrado" | "cliente_ambiguo" | "demasiados_clientes" | "sin_factura_abierta" | "varias_facturas" | "factura_no_encontrada" | "sin_permiso";
+
+export interface NiikoOptions {
+  /** The workspace API key. Shown ONCE, when created in Settings. */
+  apiKey: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export class Niiko {
+  #apiKey: string;
+  #baseUrl: string;
+  #fetch: typeof fetch;
+
+  constructor(o: NiikoOptions) {
+    if (!o.apiKey) throw new Error("niiko: apiKey is required");
+    this.#apiKey = o.apiKey;
+    this.#baseUrl = (o.baseUrl ?? "https://niiko.org").replace(/\/+$/, "");
+    this.#fetch = o.fetch ?? fetch;
+  }
+
+  async #exercise<T>(action: string, body: unknown, idempotencyKey?: string): Promise<Result<T>> {
+    const r = await this.#fetch(`${this.#baseUrl}/api/v1/actions/${action}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${this.#apiKey}`,
+        "content-type": "application/json",
+        // Send it WHENEVER you can: a timeout retry with the same key does not execute again.
+        ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+      },
+      body: JSON.stringify(body),
+    });
+
+    const json = await r.json().catch(() => null);
+    // A refusal is NOT an exception: it is a product state, and the caller must be able to branch on it.
+    // What does throw is what cannot be read — there is no decision to make there.
+    if (json && typeof json === "object" && "status" in json) return json as Result<T>;
+    throw new NiikoError(r.status, json);
+  }
+
+  /**
+   * Creates a new lead in the workspace CRM from its contact details. If a matching one already exists it is not duplicated: the reply is `ambiguous` with the candidates.
+   *
+   * `miira.lead_create` v1 — scope `miira.lead_create@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async createLead(input: CreateLeadInput, idempotencyKey?: string): Promise<Result<CreateLeadOutput>> {
+    return this.#exercise<CreateLeadOutput>("miira.lead_create", input, idempotencyKey);
+  }
+
+  /**
+   * Logs what was discussed in a call on a client's record, naming the client; optionally creates the follow-up with its date. Reads nothing and calls no one.
+   *
+   * `crm.call_logged` v1 — scope `crm.call_logged@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async loggedCall(input: LoggedCallInput, idempotencyKey?: string): Promise<Result<LoggedCallOutput>> {
+    return this.#exercise<LoggedCallOutput>("crm.call_logged", input, idempotencyKey);
+  }
+
+  /**
+   * Changes who owns a client, naming the client and the team member (by name or email). If either is ambiguous it refuses with the list.
+   *
+   * `crm.owner_assigned` v1 — scope `crm.owner_assigned@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async assignedOwner(input: AssignedOwnerInput, idempotencyKey?: string): Promise<Result<AssignedOwnerOutput>> {
+    return this.#exercise<AssignedOwnerOutput>("crm.owner_assigned", input, idempotencyKey);
+  }
+
+  /**
+   * Moves a client's open deal to another pipeline stage, naming the client and the stage. Creates no deals: with no open deal it refuses, and with several it refuses with the list.
+   *
+   * `crm.stage_moved` v1 — scope `crm.stage_moved@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async movedStage(input: MovedStageInput, idempotencyKey?: string): Promise<Result<MovedStageOutput>> {
+    return this.#exercise<MovedStageOutput>("crm.stage_moved", input, idempotencyKey);
+  }
+
+  /**
+   * Prepares an invoice as a DRAFT for a client named by name, with its lines and taxes. Does NOT issue it, does NOT number it and does NOT count as debt: a person reviews and issues it in Kiipu. Does not create the client if it does not exist.
+   *
+   * `kiipu.invoice_proposed` v1 — scope `kiipu.invoice_proposed@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async proposedInvoice(input: ProposedInvoiceInput, idempotencyKey?: string): Promise<Result<ProposedInvoiceOutput>> {
+    return this.#exercise<ProposedInvoiceOutput>("kiipu.invoice_proposed", input, idempotencyKey);
+  }
+
+  /**
+   * Creates a reminder (a task with date and time) on a client named by name. Does not log a call: that is crm.call_logged. Does not create the client if it does not exist.
+   *
+   * `crm.task_created` v1 — scope `crm.task_created@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async createdTask(input: CreatedTaskInput, idempotencyKey?: string): Promise<Result<CreatedTaskOutput>> {
+    return this.#exercise<CreatedTaskOutput>("crm.task_created", input, idempotencyKey);
+  }
+
+  /**
+   * Opens a new deal in the pipeline for a client named by name, with a title, an optional value in USD, an optional stage (by name; without it, the first one) and an optional owner. Does not check for other open deals: it returns how many remain so a duplicate is visible. Does not win or lose it: that is crm.stage_moved.
+   *
+   * `crm.deal_created` v1 — scope `crm.deal_created@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async createdDeal(input: CreatedDealInput, idempotencyKey?: string): Promise<Result<CreatedDealOutput>> {
+    return this.#exercise<CreatedDealOutput>("crm.deal_created", input, idempotencyKey);
+  }
+
+  /**
+   * Saves a note on a client's record, naming the client: something to know next time, with no call and no date. For a call use crm.call_logged; for a dated reminder, crm.task_created.
+   *
+   * `crm.note_added` v1 — scope `crm.note_added@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async addedNote(input: AddedNoteInput, idempotencyKey?: string): Promise<Result<AddedNoteOutput>> {
+    return this.#exercise<AddedNoteOutput>("crm.note_added", input, idempotencyKey);
+  }
+
+  /**
+   * Adds a person (name, and optionally email, phone and role) to a client's record, naming the client. Does not make them the primary contact and does not create the client. If someone with that email or phone already existed, the reply says so but does not block it.
+   *
+   * `crm.contact_added` v1 — scope `crm.contact_added@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async addedContact(input: AddedContactInput, idempotencyKey?: string): Promise<Result<AddedContactOutput>> {
+    return this.#exercise<AddedContactOutput>("crm.contact_added", input, idempotencyKey);
+  }
+
+  /**
+   * Quotes sending the SAME WhatsApp message to several clients named by name (up to 50). Sends NOTHING: per client, it says whether the text goes as-is (24-hour window open, free), whether an approved template is needed and what it costs, or why that client cannot be messaged. Returns a signed quote valid for 15 minutes; to send, call miira.broadcast_sent with it. Show the quote to the person first.
+   *
+   * `miira.broadcast_quoted` v1 — scope `miira.broadcast_quoted@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async quotedBroadcast(input: QuotedBroadcastInput, idempotencyKey?: string): Promise<Result<QuotedBroadcastOutput>> {
+    return this.#exercise<QuotedBroadcastOutput>("miira.broadcast_quoted", input, idempotencyKey);
+  }
+
+  /**
+   * Sends the WhatsApp broadcast quoted by miira.broadcast_quoted, exactly to whom and how the quote said. If anything changed (window, consent, rate) it refuses with a new quote to confirm again. Costs money when templates are involved: do not call it without the person having seen the cost.
+   *
+   * `miira.broadcast_sent` v1 — scope `miira.broadcast_sent@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async sentBroadcast(input: SentBroadcastInput, idempotencyKey?: string): Promise<Result<SentBroadcastOutput>> {
+    return this.#exercise<SentBroadcastOutput>("miira.broadcast_sent", input, idempotencyKey);
+  }
+
+  /**
+   * Voids a DRAFT invoice (one created with kiipu.invoice_proposed and not yet issued), by its id or by the client's name when it is their only draft. Does not void issued invoices: that is for a person in Kiipu.
+   *
+   * `kiipu.draft_voided` v1 — scope `kiipu.draft_voided@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async voidedDraft(input: VoidedDraftInput, idempotencyKey?: string): Promise<Result<VoidedDraftOutput>> {
+    return this.#exercise<VoidedDraftOutput>("kiipu.draft_voided", input, idempotencyKey);
+  }
+
+  /**
+   * Leaves in the Kiipu approval queue the notice that a client (by name) paid a given amount of an open invoice. Does NOT apply the payment and touches no balances: a person checks it against the bank and applies it. If the client has several open invoices the number must be given.
+   *
+   * `kiipu.payment_reported` v1 — scope `kiipu.payment_reported@1`.
+   *
+   * Needs **two** permissions: a key with that scope, and the workspace having switched the action on.
+   */
+  async reportedPayment(input: ReportedPaymentInput, idempotencyKey?: string): Promise<Result<ReportedPaymentOutput>> {
+    return this.#exercise<ReportedPaymentOutput>("kiipu.payment_reported", input, idempotencyKey);
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@vorluno/niiko-sdk",
+  "version": "0.1.0",
+  "description": "Generated client for the niiko actions API — it exposes verbs, not rows.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "license": "Apache-2.0",
+  "author": "Vorluno (https://vorluno.dev)",
+  "homepage": "https://developers.niiko.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vorluno/niiko-sdk-typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vorluno/niiko-sdk-typescript/issues"
+  },
+  "keywords": [
+    "niiko",
+    "api",
+    "sdk",
+    "crm",
+    "leads"
+  ],
+  "files": [
+    "dist",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "engines": {
+    "node": ">=18"
+  }
+}