@rwa-xyz/partners 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RWA.xyz
+
+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,163 @@
-# Temporary Holding Version
+# @rwa-xyz/partners
 
-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.
+The RWA.xyz Partners API client for TypeScript and JavaScript: submit your
+assets' NAV and yield, and read back what RWA.xyz stored.
+
+**Beta.** This client is in beta until 1.0: a new minor version may change a
+call or an option you use, so pin it (see Versions below). The Partners API it
+calls isn't in beta.
+
+```sh
+npm install @rwa-xyz/partners
+```
+
+Node 20 or later. No dependencies. ES modules and CommonJS. Run it on a server,
+never in a browser: your key must stay private.
+
+## Submit metrics
+
+Create a key in RWA.xyz Partners under **Settings → API Keys**, and set it as
+`RWA_API_KEY`. There is no sandbox: what you submit is saved for real.
+
+```ts
+import { RwaPartners } from "@rwa-xyz/partners";
+
+const client = new RwaPartners(); // reads RWA_API_KEY
+
+const me = await client.me();
+console.log(me.organization.name, me.key.scopes);
+
+const report = await client.metrics.submit([
+    { id: "USDY", date: "2026-10-28", metrics: { net_asset_value: 1.0012 } },
+    { id: "USDY", date: "2026-10-29", metrics: { net_asset_value: 1.0013 } },
+]);
+
+console.log(`Stored ${report.succeeded} of ${report.submitted}`);
+for (const failure of report.failures) {
+    console.error(failure.id, failure.date, failure.code, failure.message);
+}
+```
+
+A record's `id` is the asset's ticker or UUID. Until the asset is published, use
+the ticker on your saved listing: save its name and ticker in RWA.xyz Partners
+first. Its `date` is the UTC day the values apply to, never the day you send
+them, and no later than tomorrow. A field you leave out keeps its saved value.
+
+The two fields most assets send, as JSON numbers at full precision:
+
+- `net_asset_value`: per token, not total AUM, in your listing's Denomination
+  Currency.
+- `net_yield_1d_rate`: the unannualized 1-day yield as a decimal, not a percent.
+
+`client.assets.get(id)` answers `expected_metrics`, the fields RWA.xyz expects for
+that asset. Send them when NAV changes or yield is updated, before 1:00 AM UTC the
+following day.
+
+`submit` takes any number of records, for any assets and dates, and sends them
+200 to a request (`batchSize` changes that). It answers one result per record,
+in the order you passed them. A refused record does not throw: read
+`report.failures`, or call `report.throwIfFailed()`. Each failure has a `code` to
+branch on (`invalid_id`, `invalid_date`, `invalid_record`, `unknown_field`,
+`invalid_value`, `unowned_asset`, `rejected_registration`, `ambiguous_asset`,
+`write_failed`) and a `message`
+for a person. Only `write_failed` is worth sending again unchanged, and the
+client has already tried once, unless a later record in its batch is for the
+same asset and day. Send it with every later record for that asset and day
+after it, or it puts back the values they replaced. `report.deprecatedFields`
+lists retired fields you sent. A NaN or
+infinite value is refused before anything is sent: JSON would carry it as `null`,
+which means "keep the saved value".
+
+If a request fails outright, the error carries `partialReport`: the results of
+every batch answered before it. Every record is an upsert keyed by asset and
+date, so sending the same records again is safe either way.
+
+## Read back
+
+```ts
+const assets = await client.assets.list();
+console.log(assets.map((asset) => asset.ticker));
+
+const usdy = await client.assets.get("USDY", { limit: 30, order: "desc" });
+console.log(usdy.status, usdy.expected_metrics, usdy.quarantines);
+
+for await (const day of client.assets.history("USDY", { order: "asc" })) {
+    console.log(day.date, day.net_asset_value);
+}
+```
+
+`expected_metrics` lists the fields RWA.xyz expects for the asset. An asset
+still in review is not listed, but is found by its ticker, with `status`
+`"in_review"`. `quarantines` lists values held back while they are reviewed.
+`history` walks every stored day, fetching each page as you reach it.
+
+## Errors and retries
+
+A request RWA.xyz refuses throws an `APIError` subclass: `BadRequestError` (400),
+`AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError`
+(404), `PayloadTooLargeError` (413), `RateLimitError` (429) or
+`InternalServerError` (5xx), with `status`, `headers` and the response `body`. No
+answer at all throws `APIConnectionError`, or `APITimeoutError`. All of them are
+a `RwaPartnersError`.
+
+A read is retried twice after a 408, 429, 500, 502, 503 or 504, no answer, or
+an answer cut off part-way, honouring `Retry-After`. A submission is retried
+only when the API has stopped working on it: after a 408, 429, 500 or 503, a
+connection that never opened, or an answer cut off part-way. After no answer,
+or a 502 or 504, the API may still be saving it, so the client throws rather
+than send it again, which could put an old value back over a newer one.
+
+## Configuration
+
+| Option | Default | |
+| --- | --- | --- |
+| `apiKey` | `RWA_API_KEY` | Your API key. |
+| `baseUrl` | `RWA_API_BASE_URL`, then production | Where requests go. |
+| `maxRetries` | `2` | How many times a failed request is retried. |
+| `timeoutMs` | `120000` | How long each attempt may take. |
+| `fetch` | The global one | What sends requests: for a proxy, or your own headers. |
+
+## Test your code
+
+Pass a stand-in for `fetch`, and everything else runs for real.
+
+```ts
+import assert from "node:assert/strict";
+import { RwaPartners } from "@rwa-xyz/partners";
+
+const client = new RwaPartners({
+    apiKey: "test",
+    fetch: async () =>
+        Response.json({
+            results: [
+                {
+                    id: "USDY",
+                    date: "2026-10-28",
+                    status: "error",
+                    code: "unowned_asset",
+                    error: "Asset not found in organization",
+                },
+            ],
+        }),
+});
+
+const report = await client.metrics.submit([
+    { id: "USDY", date: "2026-10-28", metrics: { net_asset_value: 1.0012 } },
+]);
+
+assert.equal(report.failures[0]?.code, "unowned_asset");
+```
+
+## Versions
+
+This package and `rwa-partners` for Python share one version number. Until 1.0
+it's in beta, and a new minor version may change anything, so pin it: `~0.1.0`. New fields, calls
+and refusal codes can arrive in any version.
+
+## Documentation
+
+The full guides are at https://partners.rwa.xyz/docs/sdks (sign in to RWA.xyz
+Partners).
+
+For help, use **Contact Support** in RWA.xyz Partners, or email team@rwa.xyz.
+Include the asset, the date and the error's message, never your API key.

package/dist/cjs/assets.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Reading assets: the ones a key may submit for, and each one's attributes,
+ * expected metrics and metric history.
+ *
+ * @module sdk/typescript/assets
+ */
+import type { components, operations } from "./generated/openapi.js";
+import { type TransportOptions } from "./http.js";
+type Schemas = components["schemas"];
+/** An asset in the catalogue: one your key may submit metrics for. */
+export type CatalogueAsset = Schemas["CatalogueAsset"];
+/** One asset, its expected metrics and a page of its metric history. */
+export type AssetDetail = Schemas["AssetDetail"];
+/** One day of an asset's stored metrics. */
+export type MetricHistoryRow = Schemas["MetricHistoryRow"];
+export type GetAssetOptions = NonNullable<operations["getAsset"]["parameters"]["query"]>;
+export interface HistoryOptions {
+    /** `desc` (newest first, the default) or `asc`. */
+    readonly order?: "asc" | "desc";
+    /** Rows per request, 1 to 365. */
+    readonly pageSize?: number;
+}
+export declare class Assets {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /** The published assets your organization may submit metrics for. */
+    list(options?: {
+        organizationId?: string;
+    }): Promise<CatalogueAsset[]>;
+    /**
+     * One asset by ticker, uuid or Partners id, with one page of its history.
+     * An asset still in review is found by its ticker, `status: "in_review"`.
+     */
+    get(identifier: string, options?: GetAssetOptions): Promise<AssetDetail>;
+    /** Every day of an asset's stored metrics, page after page. */
+    history(identifier: string, options?: HistoryOptions): AsyncGenerator<MetricHistoryRow, void, undefined>;
+}
+export {};

package/dist/cjs/assets.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Reading assets: the ones a key may submit for, and each one's attributes,
+ * expected metrics and metric history.
+ *
+ * @module sdk/typescript/assets
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Assets = void 0;
+const http_js_1 = require("./http.js");
+class Assets {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** The published assets your organization may submit metrics for. */
+    async list(options = {}) {
+        const { body } = await (0, http_js_1.send)(this.transport, {
+            method: "GET",
+            path: "/v1/assets",
+            query: { organization_id: options.organizationId },
+        });
+        return body.assets;
+    }
+    /**
+     * One asset by ticker, uuid or Partners id, with one page of its history.
+     * An asset still in review is found by its ticker, `status: "in_review"`.
+     */
+    async get(identifier, options = {}) {
+        const { body } = await (0, http_js_1.send)(this.transport, {
+            method: "GET",
+            path: `/v1/assets/${encodeURIComponent(identifier)}`,
+            query: { ...options },
+        });
+        return body;
+    }
+    /** Every day of an asset's stored metrics, page after page. */
+    async *history(identifier, options = {}) {
+        let cursor;
+        for (;;) {
+            const page = await this.get(identifier, {
+                order: options.order,
+                limit: options.pageSize,
+                cursor,
+            });
+            yield* page.metrics;
+            const next = page.pagination.has_more
+                ? page.pagination.next_cursor
+                : null;
+            if (!next)
+                return;
+            cursor = next;
+        }
+    }
+}
+exports.Assets = Assets;

package/dist/cjs/client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The client: one API key, one base URL, and the calls an integration makes.
+ *
+ * @module sdk/typescript/client
+ */
+import { Assets } from "./assets.js";
+import { type components } from "./generated/openapi.js";
+import { Metrics } from "./metrics.js";
+/** Who a key is: its scopes, its user and the organization it acts for. */
+export type Caller = components["schemas"]["Caller"];
+export interface ClientOptions {
+    /** Your Partners API key. Defaults to the `RWA_API_KEY` variable. */
+    readonly apiKey?: string;
+    /**
+     * Where requests go. Defaults to the `RWA_API_BASE_URL` variable, then
+     * production (`DEFAULT_BASE_URL`).
+     */
+    readonly baseUrl?: string;
+    /**
+     * Retries after a 408, 429, 5xx or no answer; a submission only when the
+     * API has stopped working on it. Default 2.
+     */
+    readonly maxRetries?: number;
+    /** Per attempt. Default 120 000: a 200-record batch takes up to a minute. */
+    readonly timeoutMs?: number;
+    /** A `fetch` to send requests with. Defaults to the global one. */
+    readonly fetch?: typeof fetch;
+}
+/** Production: the server the API's own description names. */
+export declare const DEFAULT_BASE_URL = "https://partners-api.rwa.xyz";
+export declare class RwaPartners {
+    readonly assets: Assets;
+    readonly metrics: Metrics;
+    private readonly transport;
+    constructor(options?: ClientOptions);
+    /** What this key is and may do: also the check that it still works. */
+    me(): Promise<Caller>;
+}

package/dist/cjs/client.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * The client: one API key, one base URL, and the calls an integration makes.
+ *
+ * @module sdk/typescript/client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RwaPartners = exports.DEFAULT_BASE_URL = void 0;
+const assets_js_1 = require("./assets.js");
+const openapi_js_1 = require("./generated/openapi.js");
+const http_js_1 = require("./http.js");
+const metrics_js_1 = require("./metrics.js");
+/** Production: the server the API's own description names. */
+exports.DEFAULT_BASE_URL = openapi_js_1.SERVER_URL;
+class RwaPartners {
+    assets;
+    metrics;
+    transport;
+    constructor(options = {}) {
+        this.transport = {
+            apiKey: (0, http_js_1.resolveApiKey)(options.apiKey),
+            baseUrl: options.baseUrl ||
+                (0, http_js_1.environmentVariable)("RWA_API_BASE_URL") ||
+                exports.DEFAULT_BASE_URL,
+            fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+            maxRetries: options.maxRetries ?? 2,
+            timeoutMs: options.timeoutMs ?? 120_000,
+            sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        };
+        // Not enumerable, so logging or serializing the client never prints it.
+        Object.defineProperty(this.transport, "apiKey", { enumerable: false });
+        this.assets = new assets_js_1.Assets(this.transport);
+        this.metrics = new metrics_js_1.Metrics(this.transport);
+    }
+    /** What this key is and may do: also the check that it still works. */
+    async me() {
+        const { body } = await (0, http_js_1.send)(this.transport, {
+            method: "GET",
+            path: "/v1/me",
+        });
+        return body;
+    }
+}
+exports.RwaPartners = RwaPartners;

package/dist/cjs/errors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What the client throws. An `APIError` is an answer the API gave; an
+ * `APIConnectionError` is no answer at all; `SubmissionFailedError` is a
+ * report you asked to throw (`SubmissionReport.throwIfFailed`).
+ *
+ * @module sdk/typescript/errors
+ */
+import type { SubmissionReport } from "./metrics.js";
+/** Everything this package throws. */
+export declare class RwaPartnersError extends Error {
+    name: string;
+    /**
+     * When `metrics.submit` stops part-way, the results of every batch it
+     * had answered in full: what to skip when you send the rest again.
+     */
+    partialReport?: SubmissionReport;
+}
+/** The API answered, with an error status. */
+export declare class APIError extends RwaPartnersError {
+    readonly status: number;
+    /** The parsed response body, or its text when it was not JSON. */
+    readonly body: unknown;
+    readonly headers: Headers;
+    name: string;
+    constructor(status: number, 
+    /** The parsed response body, or its text when it was not JSON. */
+    body: unknown, headers: Headers);
+}
+/** 400: the request itself was malformed, and nothing was saved. */
+export declare class BadRequestError extends APIError {
+    name: string;
+}
+/** 401: no key was sent, or it is unknown, revoked or expired. */
+export declare class AuthenticationError extends APIError {
+    name: string;
+}
+/** 403: the key may not do this; `body.reason` says why. */
+export declare class PermissionDeniedError extends APIError {
+    name: string;
+}
+/** 404: nothing your key may read goes by that identifier. */
+export declare class NotFoundError extends APIError {
+    name: string;
+}
+/** 413: the body is over the API's size limit. */
+export declare class PayloadTooLargeError extends APIError {
+    name: string;
+}
+/** 429: too many requests, after every retry the client was allowed. */
+export declare class RateLimitError extends APIError {
+    name: string;
+}
+/** 5xx: a failure on RWA.xyz's side, after any retries. */
+export declare class InternalServerError extends APIError {
+    name: string;
+}
+/** The error class for an error status. */
+export declare function apiErrorFor(status: number, body: unknown, headers: Headers): APIError;
+/**
+ * No answer: the network failed, after any retries. A submission is not sent
+ * again while the API may still be saving it.
+ */
+export declare class APIConnectionError extends RwaPartnersError {
+    name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** No answer within the timeout, after any retries. */
+export declare class APITimeoutError extends APIConnectionError {
+    name: string;
+}
+/** Thrown by `SubmissionReport.throwIfFailed` when a record was refused. */
+export declare class SubmissionFailedError extends RwaPartnersError {
+    readonly report: SubmissionReport;
+    name: string;
+    constructor(report: SubmissionReport);
+}

package/dist/cjs/errors.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * What the client throws. An `APIError` is an answer the API gave; an
+ * `APIConnectionError` is no answer at all; `SubmissionFailedError` is a
+ * report you asked to throw (`SubmissionReport.throwIfFailed`).
+ *
+ * @module sdk/typescript/errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubmissionFailedError = exports.APITimeoutError = exports.APIConnectionError = exports.InternalServerError = exports.RateLimitError = exports.PayloadTooLargeError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIError = exports.RwaPartnersError = void 0;
+exports.apiErrorFor = apiErrorFor;
+// // // //
+/** Everything this package throws. */
+class RwaPartnersError extends Error {
+    name = "RwaPartnersError";
+    /**
+     * When `metrics.submit` stops part-way, the results of every batch it
+     * had answered in full: what to skip when you send the rest again.
+     */
+    partialReport;
+}
+exports.RwaPartnersError = RwaPartnersError;
+/** The message an error body carries, in whichever field it carries it. */
+function messageOf(status, body) {
+    if (body && typeof body === "object") {
+        const fields = body;
+        for (const key of ["message", "error"]) {
+            if (typeof fields[key] === "string") {
+                const reason = typeof fields.reason === "string"
+                    ? `: ${fields.reason}`
+                    : "";
+                return `${status} ${fields[key]}${reason}`;
+            }
+        }
+    }
+    return `${status} ${typeof body === "string" ? body : "error"}`;
+}
+/** The API answered, with an error status. */
+class APIError extends RwaPartnersError {
+    status;
+    body;
+    headers;
+    name = "APIError";
+    constructor(status, 
+    /** The parsed response body, or its text when it was not JSON. */
+    body, headers) {
+        super(messageOf(status, body));
+        this.status = status;
+        this.body = body;
+        this.headers = headers;
+    }
+}
+exports.APIError = APIError;
+/** 400: the request itself was malformed, and nothing was saved. */
+class BadRequestError extends APIError {
+    name = "BadRequestError";
+}
+exports.BadRequestError = BadRequestError;
+/** 401: no key was sent, or it is unknown, revoked or expired. */
+class AuthenticationError extends APIError {
+    name = "AuthenticationError";
+}
+exports.AuthenticationError = AuthenticationError;
+/** 403: the key may not do this; `body.reason` says why. */
+class PermissionDeniedError extends APIError {
+    name = "PermissionDeniedError";
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+/** 404: nothing your key may read goes by that identifier. */
+class NotFoundError extends APIError {
+    name = "NotFoundError";
+}
+exports.NotFoundError = NotFoundError;
+/** 413: the body is over the API's size limit. */
+class PayloadTooLargeError extends APIError {
+    name = "PayloadTooLargeError";
+}
+exports.PayloadTooLargeError = PayloadTooLargeError;
+/** 429: too many requests, after every retry the client was allowed. */
+class RateLimitError extends APIError {
+    name = "RateLimitError";
+}
+exports.RateLimitError = RateLimitError;
+/** 5xx: a failure on RWA.xyz's side, after any retries. */
+class InternalServerError extends APIError {
+    name = "InternalServerError";
+}
+exports.InternalServerError = InternalServerError;
+/** The error class for an error status. */
+function apiErrorFor(status, body, headers) {
+    const ErrorClass = status === 400
+        ? BadRequestError
+        : status === 401
+            ? AuthenticationError
+            : status === 403
+                ? PermissionDeniedError
+                : status === 404
+                    ? NotFoundError
+                    : status === 413
+                        ? PayloadTooLargeError
+                        : status === 429
+                            ? RateLimitError
+                            : status >= 500
+                                ? InternalServerError
+                                : APIError;
+    return new ErrorClass(status, body, headers);
+}
+/**
+ * No answer: the network failed, after any retries. A submission is not sent
+ * again while the API may still be saving it.
+ */
+class APIConnectionError extends RwaPartnersError {
+    name = "APIConnectionError";
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+exports.APIConnectionError = APIConnectionError;
+/** No answer within the timeout, after any retries. */
+class APITimeoutError extends APIConnectionError {
+    name = "APITimeoutError";
+}
+exports.APITimeoutError = APITimeoutError;
+/** Thrown by `SubmissionReport.throwIfFailed` when a record was refused. */
+class SubmissionFailedError extends RwaPartnersError {
+    report;
+    name = "SubmissionFailedError";
+    constructor(report) {
+        const [first] = report.failures;
+        super(`${report.failures.length} of ${report.submitted} records were not saved` +
+            (first
+                ? `; the first, ${first.id} on ${first.date}: ${first.message}`
+                : ""));
+        this.report = report;
+    }
+}
+exports.SubmissionFailedError = SubmissionFailedError;