@vestiarion/sdk 0.1.0 → 0.2.0

package/README.md

@@ -12,10 +12,11 @@ It has no dependencies, and runs on Node 20 or later, Deno, Bun and edge runtime
 ## Install
 
 ```bash
-npm install https://www.vestiarion.xyz/sdk/vestiarion-sdk-0.1.0.tgz
+npm install @vestiarion/sdk
 ```
 
-pnpm, Yarn and Bun take the same URL. The package is ESM only.
+pnpm, Yarn and Bun install it the same way. The package is ESM only. Each version is also served as a tarball, such as
+`https://www.vestiarion.xyz/sdk/vestiarion-sdk-0.2.0.tgz`, which `npm install` takes as it is.
 
 ## Read
 
@@ -38,9 +39,10 @@ workspace.
 
 ## Add records
 
-A key with write access ("Can also add counterparties and invoices") adds counterparties and invoices.
+A key with write access ("Can also add records") adds counterparties, invoices, milestones and payee links.
 - The agent decides each invoice as it decides one typed into the console, with every guardrail.
-- An address added this way waits for a person in the workspace to confirm it.
+- A milestone starts pending. GitHub verifies it once its pull request is merged, or a person does; then the agent decides.
+- An address added this way, or entered by a payee through a link, waits for a person in the workspace to confirm it.
 
 ```ts
 const counterparty = await vestiarion.counterparties.create(
@@ -55,6 +57,20 @@ const invoice = await vestiarion.invoices.create(
 
 Pass your own record's id as `idempotencyKey`, so that your own retries cannot add it twice either.
 
+Pay a contributor when their pull request merges, and ask a new payee for their address:
+
+```ts
+const milestone = await vestiarion.milestones.create(
+  { contractorId: contractor.id, title: "CSV export for EURC", amount: "150.00", verificationSource: "https://github.com/acme/app/pull/42" },
+  { idempotencyKey: "pr-acme-app-42" }
+);
+const link = await vestiarion.payeeLinks.create({ counterpartyId: contractor.id });
+// Send link.url to the payee: it is shown only in this answer.
+```
+
+A payee link takes no `idempotencyKey`: the API keeps only the link's hash, so a repeat makes a new link and the unused
+one stops working.
+
 ## Errors and retries
 
 Every failure is a `VestiarionError`. It carries:
@@ -68,7 +84,8 @@ A request is retried twice by default after:
 - a `500`, `502`, `503` or `504`;
 - a timeout or a network failure.
 
-A write always carries an `Idempotency-Key`, so retrying it never adds the record twice.
+A write carries an `Idempotency-Key`, so retrying it never adds the record twice. A payee link is the exception: a retry
+makes a new link, which replaces the first.
 
 ## Webhooks
 

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type FetchLike } from "./http.js";
-import type { Counterparty, CounterpartyDetail, CreateCounterpartyInput, CreateInvoiceInput, Insights, Invoice, LedgerEntry, LedgerVerification, ListCounterpartiesParams, ListInvoicesParams, ListLedgerEntriesParams, ListMilestonesParams, Milestone, Page, Status, Treasury } from "./types.js";
+import type { Counterparty, CounterpartyDetail, CreateCounterpartyInput, CreateInvoiceInput, CreateMilestoneInput, CreatePayeeLinkInput, Insights, Invoice, LedgerEntry, LedgerVerification, ListCounterpartiesParams, ListInvoicesParams, ListLedgerEntriesParams, ListMilestonesParams, Milestone, Page, PayeeLink, Status, Treasury } from "./types.js";
 /** Where the API is, unless `baseUrl` says otherwise. */
 export declare const DEFAULT_BASE_URL = "https://www.vestiarion.xyz";
 export interface VestiarionOptions {
@@ -49,7 +49,16 @@ export declare class Vestiarion {
         get(id: string): Promise<CounterpartyDetail>;
         create(input: CreateCounterpartyInput, options?: WriteOptions): Promise<Counterparty>;
     };
-    readonly milestones: Collection<Milestone, ListMilestonesParams>;
+    readonly milestones: Collection<Milestone, ListMilestonesParams> & {
+        create(input: CreateMilestoneInput, options?: WriteOptions): Promise<Milestone>;
+    };
+    /**
+     * One-time links where a payee enters the address they are paid at. A link's `url` is in the answer only: send it to
+     * the payee. Making one revokes the payee's unused link, so a retry gives a working link too.
+     */
+    readonly payeeLinks: {
+        create(input: CreatePayeeLinkInput): Promise<PayeeLink>;
+    };
     readonly treasury: {
         get(): Promise<Treasury>;
     };

package/dist/client.js

@@ -48,6 +48,11 @@ export class Vestiarion {
     invoices;
     counterparties;
     milestones;
+    /**
+     * One-time links where a payee enters the address they are paid at. A link's `url` is in the answer only: send it to
+     * the payee. Making one revokes the payee's unused link, so a retry gives a working link too.
+     */
+    payeeLinks;
     treasury;
     insights;
     constructor(options) {
@@ -84,7 +89,14 @@ export class Vestiarion {
             get: (id) => one(`/api/v1/counterparties/${encodeURIComponent(id)}`),
             create: (input, write) => add("/api/v1/counterparties", input, write),
         };
-        this.milestones = collection(transport, "/api/v1/milestones");
+        this.milestones = {
+            ...collection(transport, "/api/v1/milestones"),
+            create: (input, write) => add("/api/v1/milestones", input, write),
+        };
+        // The API keeps no outcome for a payee link's key, so none is sent (write API part 2, W3).
+        this.payeeLinks = {
+            create: (input) => transport.request({ method: "POST", path: "/api/v1/payee-links", body: input, idempotencyKey: null }).then((answer) => answer.data),
+        };
         this.treasury = { get: () => one("/api/v1/treasury") };
         this.insights = { get: () => one("/api/v1/insights") };
     }

package/dist/http.d.ts

@@ -29,7 +29,8 @@ export interface RequestSpec {
     path: string;
     query?: object;
     body?: unknown;
-    idempotencyKey?: string;
+    /** A write's key: the caller's, or a fresh one when left out. `null` sends none, for a write that keeps no outcome for one. */
+    idempotencyKey?: string | null;
 }
 export interface Transport {
     request<T>(spec: RequestSpec): Promise<T>;

package/dist/http.js

@@ -121,8 +121,10 @@ export function createTransport(options) {
         let body;
         if (spec.method === "POST") {
             headers["content-type"] = "application/json";
-            // Every write carries a key, so retrying it can never add the record twice (R6).
-            headers["idempotency-key"] = spec.idempotencyKey ?? uuid();
+            // Every write that keeps an outcome for a key carries one, so retrying it can never add the record twice (R6). A
+            // payee link keeps none, since that would store the link: a retry makes a new link, which replaces the first.
+            if (spec.idempotencyKey !== null)
+                headers["idempotency-key"] = spec.idempotencyKey ?? uuid();
             body = JSON.stringify(spec.body ?? {});
         }
         for (let attempt = 0;; attempt += 1) {

package/dist/types.d.ts

@@ -174,6 +174,16 @@ export interface Milestone {
     } | null;
     createdAt: string;
 }
+/** A one-time link for a payee to enter the address they are paid at. That address waits for a person in the workspace to confirm it before the agent pays to it. */
+export interface PayeeLink {
+    /** The link's own id. It is not the link: that is `url`. */
+    id: string;
+    counterpartyId: string;
+    /** The one-time page where the payee enters their address. It is in this answer only: Vestiarion keeps just its hash. Send it to the payee yourself. */
+    url: string;
+    /** When the link stops working, 7 days after it was made. It also stops once the payee has used it, or a newer link replaces it. */
+    expiresAt: string;
+}
 /** The workspace's accounts, reserve, obligations, latest forecast and recent treasury moves. */
 export interface Treasury {
     accounts: Array<{
@@ -335,6 +345,22 @@ export interface CreateCounterpartyInput {
     /** Where it is emailed once a payment to it is confirmed. */
     noticeEmail?: string;
 }
+/** A milestone to add. It starts pending: the agent pays it only once it is verified, by GitHub or by a person, and only after its own checks. */
+export interface CreateMilestoneInput {
+    /** The `id` of the contractor or vendor to pay, from `GET /api/v1/counterparties` or from the answer that added it. A client is not paid for milestones. */
+    contractorId: string;
+    /** What was delivered, 3 to 160 characters. */
+    title: string;
+    /** What the work is paid, in USDC, with at most 6 decimal places. A decimal string such as `"250.00"` keeps it exact; a number is read the same way. */
+    amount: string | number;
+    /** A link to the delivered work: https, up to 500 characters. A GitHub pull request (`https://github.com/<owner>/<repo>/pull/<number>`) is checked by the agent, which verifies the milestone once it is merged. Any other link is evidence for the person who verifies the milestone on Contractors. */
+    verificationSource?: string;
+}
+/** Who the link is for. */
+export interface CreatePayeeLinkInput {
+    /** The `id` of the vendor or contractor who is to enter the address they are paid at. A client gets no link: the agent never pays one. */
+    counterpartyId: string;
+}
 /** The query parameters of `list-ledger-entries`. */
 export interface ListLedgerEntriesParams {
     /** How many items to return. Defaults to 50; a larger value is capped at 200. */

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, sent in every request's `User-Agent`. tests/sdk-package.test.ts holds it to package.json. */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** This package's version, sent in every request's `User-Agent`. tests/sdk-package.test.ts holds it to package.json. */
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestiarion/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A typed client for the Vestiarion API and its signed webhooks.",
   "license": "MIT",
   "type": "module",