@arbol-ai/sdk 1.20261017.200040 → 2.1.0

package/README.md

@@ -3,8 +3,9 @@
 The Arbol API for TypeScript and JavaScript, generated by
 [Cloudflare Forge](https://github.com/cloudflare/forge) from the platform's public OpenAPI,
 [`https://api.getarbol.com/openapi.json`](https://api.getarbol.com/openapi.json). Everything in `src/`
-is Forge's TypeScript output, unedited, and the package's version is the API release it was generated
-from (`1.YYYYMMDD.n`).
+is Forge's TypeScript output, unedited. Versions are semver, and each one records the OpenAPI it was
+generated from: `npm view @arbol-ai/sdk@<version> arbol.openapi` prints its `release` (`info.version`)
+and content hash (`sha256`).
 
 ```sh
 npm install @arbol-ai/sdk
@@ -56,14 +57,63 @@ The server authorizes every call: a method in the client is not a grant.
 bun install
 bun run forge       # build the pinned Cloudflare Forge with cargo into .forge/ (once; needs Rust)
 bun run openapi     # download https://api.getarbol.com/openapi.json
-bun run generate    # src/ from openapi.json with `forge --target ts`; the version from its info.version
+bun run generate    # src/ from openapi.json with `forge --target ts`; its release and hash in arbol.openapi
+bun run hash        # the OpenAPI's content hash (see Releases)
 bun run verify      # typecheck and build dist/
 ```
 
-`openapi.json` is downloaded at generation time and not committed; `package.json`'s version is the
-OpenAPI version `src/` was generated from. Forge is pinned to its commit
+`openapi.json` is downloaded at generation time and not committed. `package.json`'s `arbol.openapi`
+records the OpenAPI `src/` was generated from, its `info.version` as `release` and its content hash as
+`sha256`; `version` and `arbol` are release metadata the workflows set. Forge is pinned to its commit
 `7f86447210b7bea3779bfdab3cd5655eade0eadb` (0.1.0) in the `forge` script.
 
+## Releases
+
+Versions are semver, independent of the OpenAPI's release number. The 1.x versions (`1.YYYYMMDD.n`)
+were the OpenAPI's date releases; 2.x starts at 2.1.0.
+
+Releases of a new OpenAPI are automatic, from the API down to the CLI:
+
+1. **Gateway.** When the Arbol API ships an OpenAPI release, the gateway sends this repository a
+   `repository_dispatch` `openapi-release` with `{ "version": "<release>" }`.
+2. **SDK (this repository).** [Generate](.github/workflows/generate.yml) runs on that dispatch, every
+   six hours, and by hand. It downloads the OpenAPI (waiting until the API serves the announced release)
+   and hashes its content. When the hash differs from `arbol.openapi.sha256` in `package.json`, it
+   regenerates `src/` with Forge, records the OpenAPI in `arbol.openapi`, and takes the highest version
+   on npm with the minor raised and the patch at 0 (2.1.0, 2.2.0, 2.3.0, …). It verifies the result,
+   commits `Release <version>` to `main` as Arbol, and publishes `@arbol-ai/sdk` to npm with
+   [Publish](.github/workflows/publish.yml), with a provenance statement.
+3. **CLI.** After publishing, Publish sends
+   [project-arbol-cli](https://github.com/getarbol/project-arbol-cli) a `repository_dispatch`
+   `sdk-release` with `{ "version": "<published version>", "openapi": { "release": "…", "sha256": "…" } }`,
+   the published `version` and `arbol.openapi`, and the CLI releases itself on it.
+
+The hash ([`scripts/release.ts`](scripts/release.ts)) is the SHA-256 hex of the OpenAPI's canonical
+JSON (object keys sorted recursively, arrays in order, no whitespace) with `info.version` removed. A new
+release number with an identical API hashes the same, so Generate commits, publishes, and announces
+nothing. A version on `main` that is not on npm yet, such as one a failed run left behind, is published
+by the next run.
+
+Changes to the SDK itself, such as a new Forge pin, are released by hand: commit them to `main`
+(regenerated with `bun run generate` when they change `src/`), then run Publish on `main` with `bump`
+`patch` (the default), `minor` or `major`:
+
+```sh
+gh workflow run publish.yml --repo getarbol/project-arbol-sdk-js --ref main -f bump=patch
+```
+
+It raises that part of the highest version on npm (while no 2.x version is published, the result is
+2.1.0 whatever the bump), commits `Release <version>` to `main`, publishes it, and announces it to the
+CLI like Generate. It refuses when `main`'s version is not on npm yet (run Generate, which publishes it),
+and when nothing that goes into the package (`src/`, `package.json`, `tsconfig.json`, `bun.lock`,
+`README.md`, `LICENSE`) changed since the commit that released `main`'s version, so the same SDK is
+never published twice. A manual release and Generate wait for each other.
+
+Generate and Publish push and dispatch as the Arbol Bot GitHub App, so their commits to `main` run
+[Verify](.github/workflows/verify.yml). They need the organization variable `ARBOL_BOT_APP_ID`, the
+organization secret `ARBOL_BOT_PRIVATE_KEY`, and the App installed with contents write access to this
+repository and project-arbol-cli. npm publishing uses the organization secret `NPM_TOKEN`.
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/dist/account/connections/client.d.ts

@@ -11,8 +11,8 @@ export interface Client {
     /**
      * Add a connection
      *
-     * Add a connection. SURA and Visoft: the owner signs in once with the
-     * credentials before anything is sealed; a refused login answers
+     * Add a connection. Provider connections: the owner verifies credentials once
+     * with the credentials before anything is sealed; a refused login answers
      * LOGIN_REJECTED with each login's result, and one that was not refused stays
      * saved. A SURA account that sees several institutions answers
      * INSTITUTION_REQUIRED with them: send the same request again with
@@ -68,6 +68,26 @@ export type CreateRequest = {
     name: string;
     password: string;
     username: string;
+} | {
+    documentType: string;
+    integration: "axxa";
+    kind: "arbol";
+    name: string;
+    password: string;
+    providerCode: string;
+    username: string;
+} | {
+    documentType: string;
+    integration: "nueva-eps";
+    kind: "arbol";
+    name: string;
+    password: string;
+    username: string;
+} | {
+    apiToken: string;
+    integration: "gmedic";
+    kind: "arbol";
+    name: string;
 } | {
     authHeader?: string;
     fileArgument?: string;
@@ -133,12 +153,14 @@ export interface UpdateRequest {
      * platform.
      */
     id: string;
+    apiToken?: string;
     authHeader?: string | null;
     /**
      * The clinic whose SIIPS the login belongs to, as visoft.clinics.list names
      * it.
      */
     clinicId?: string;
+    documentType?: string;
     /**
      * false disables the connection (its owner refuses it); true enables it
      * again.
@@ -163,6 +185,7 @@ export interface UpdateRequest {
      * Its password, exactly as typed.
      */
     password?: string;
+    providerCode?: string;
     /**
      * SURA: the logins to remove; at least one login stays.
      */

package/dist/axxa/authorizations/client.d.ts

@@ -0,0 +1,54 @@
+import { type BaseClientOptions, type RequestOptions, Transport } from "../../_/index.js";
+import type { ResponseMetadata } from "../../models.js";
+export interface ClientOptions extends BaseClientOptions {
+    /**
+     * The URL the paths of the API are relative to.
+     */
+    baseUrl: string;
+}
+export interface Client {
+    /**
+     * Look up medical authorizations
+     *
+     * Read authorizations for the supplied beneficiary document. Only a
+     * successful empty array means no matches; provider errors do not establish
+     * whether authorizations exist.
+     */
+    lookup(request: LookupRequest, options?: RequestOptions): Promise<LookupResponse>;
+}
+export declare function createClient(options: ClientOptions): Client;
+export declare function bind(transport: Transport): Client;
+export interface LookupRequest {
+    connectionId?: string;
+    documentNumber: string;
+}
+export interface LookupResponse {
+    /**
+     * Only an empty authorizations array confirms no matches. Provider failures
+     * are errors.
+     */
+    data: {
+        authorizations: {
+            authorizationNumber: string;
+            authorizedAt: string;
+            diagnosis: {
+                code: string;
+                description: string;
+            };
+            product: string;
+            requestNumber: string;
+            requestedAt: string;
+            services: {
+                code: string;
+                description: string;
+            }[];
+        }[];
+        beneficiary: {
+            documentNumber: string;
+            name: string;
+        } | null;
+    };
+    error: null;
+    metadata: ResponseMetadata;
+    success: true;
+}

package/dist/axxa/authorizations/client.js

@@ -0,0 +1,18 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+import { Transport, } from "../../_/index.js";
+export function createClient(options) {
+    return bind(new Transport(options));
+}
+export function bind(transport) {
+    return {
+        lookup: (request, options) => transport.send(LookupOperation, request, options),
+    };
+}
+const LookupOperation = {
+    method: "POST",
+    route: "/v1/axxa/authorizations/lookup",
+    body: "flat",
+    response: null,
+    errors: { "400": true, "401": true, "403": true, "404": true, "405": true, "409": true, "413": true, "415": true, "428": true, "429": true, "500": true, "502": true, "503": true, "504": true },
+};

package/dist/axxa/authorizations/index.d.ts

@@ -0,0 +1,4 @@
+export { ApiError } from "../../_/index.js";
+export type { RequestOptions } from "../../_/index.js";
+export { createClient } from "./client.js";
+export type { Client, ClientOptions, LookupRequest, LookupResponse, } from "./client.js";

package/dist/axxa/authorizations/index.js

@@ -0,0 +1,4 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+export { ApiError } from "../../_/index.js";
+export { createClient } from "./client.js";

package/dist/axxa/client.d.ts

@@ -0,0 +1,19 @@
+import { type BaseClientOptions, Transport } from "../_/index.js";
+import { type Client as AuthorizationsClient } from "./authorizations/client.js";
+import { type Client as ConnectionsClient } from "./connections/client.js";
+import { type Client as EligibilityClient } from "./eligibility/client.js";
+import { type Client as ProviderClient } from "./provider/client.js";
+export interface ClientOptions extends BaseClientOptions {
+    /**
+     * The URL the paths of the API are relative to.
+     */
+    baseUrl: string;
+}
+export interface Client {
+    readonly authorizations: AuthorizationsClient;
+    readonly connections: ConnectionsClient;
+    readonly eligibility: EligibilityClient;
+    readonly provider: ProviderClient;
+}
+export declare function createClient(options: ClientOptions): Client;
+export declare function bind(transport: Transport): Client;

package/dist/axxa/client.js

@@ -0,0 +1,30 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+import { Transport } from "../_/index.js";
+import { bind as bindAuthorizations, } from "./authorizations/client.js";
+import { bind as bindConnections, } from "./connections/client.js";
+import { bind as bindEligibility, } from "./eligibility/client.js";
+import { bind as bindProvider, } from "./provider/client.js";
+export function createClient(options) {
+    return bind(new Transport(options));
+}
+export function bind(transport) {
+    let authorizationsClient;
+    let connectionsClient;
+    let eligibilityClient;
+    let providerClient;
+    return {
+        get authorizations() {
+            return (authorizationsClient ??= bindAuthorizations(transport));
+        },
+        get connections() {
+            return (connectionsClient ??= bindConnections(transport));
+        },
+        get eligibility() {
+            return (eligibilityClient ??= bindEligibility(transport));
+        },
+        get provider() {
+            return (providerClient ??= bindProvider(transport));
+        },
+    };
+}

package/dist/axxa/connections/client.d.ts

@@ -0,0 +1,104 @@
+import { type BaseClientOptions, type RequestOptions, Transport } from "../../_/index.js";
+import { type Connection, type ConnectionPage, type DeletedObject, type ResponseMetadata } from "../../models.js";
+export interface ClientOptions extends BaseClientOptions {
+    /**
+     * The URL the paths of the API are relative to.
+     */
+    baseUrl: string;
+}
+export interface Client {
+    /**
+     * Remove a provider connection
+     *
+     * Remove the provider-owned connection before Account retires its sealed
+     * credentials. Login cooldowns remain durable.
+     */
+    delete(request: DeleteRequest, options?: RequestOptions): Promise<DeleteResponse>;
+    /**
+     * Get a provider connection
+     *
+     * One connection owned by the verified organization. Never a credential or a
+     * provider request.
+     */
+    get(request: GetRequest, options?: RequestOptions): Promise<GetResponse>;
+    /**
+     * List provider connections
+     *
+     * The organization’s Account connections, without reading credentials or
+     * contacting the provider.
+     */
+    list(request?: ListRequest, options?: RequestOptions): Promise<ListResponse>;
+    /**
+     * Verify a provider connection
+     *
+     * Verify these credentials once before Account seals them. A rejected
+     * verification changes no active credential. The durable organization-wide
+     * budget prevents replacement connections from bypassing login protection.
+     */
+    verify(request: VerifyRequest, options?: RequestOptions): Promise<VerifyResponse>;
+}
+export declare function createClient(options: ClientOptions): Client;
+export declare function bind(transport: Transport): Client;
+export interface DeleteRequest {
+    id: string;
+    body: {
+        [key: string]: unknown;
+    };
+}
+export interface DeleteResponse {
+    data: DeletedObject;
+    error: null;
+    metadata: ResponseMetadata;
+    success: true;
+}
+export interface GetRequest {
+    id: string;
+}
+export interface GetResponse {
+    data: Connection;
+    error: null;
+    metadata: ResponseMetadata;
+    success: true;
+}
+export interface ListRequest {
+    /**
+     * Opaque cursor returned by pageInfo; omit it to request the first page.
+     */
+    cursor?: string;
+    /**
+     * Direction to traverse the stable keyset ordering from the supplied cursor.
+     */
+    direction?: "forward" | "backward";
+    /**
+     * Maximum items returned in one page. Defaults to 25; larger reads require
+     * another cursor.
+     */
+    limit?: number;
+}
+export interface ListResponse {
+    data: ConnectionPage;
+    error: null;
+    metadata: ResponseMetadata;
+    success: true;
+}
+export interface VerifyRequest {
+    connectionId: string;
+    documentType: "CC" | "CE" | "NIT" | "PA" | "PT";
+    name: string;
+    password: string;
+    providerCode: string;
+    username: string;
+}
+export interface VerifyResponse {
+    data: {
+        stateRef: string;
+        status: "active";
+        summary: string;
+    } | {
+        errorCode: string;
+        status: "rejected";
+    };
+    error: null;
+    metadata: ResponseMetadata;
+    success: true;
+}

package/dist/axxa/connections/client.js

@@ -0,0 +1,42 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+import { Transport, object, } from "../../_/index.js";
+import { ConnectionCodec, ConnectionPageCodec, } from "../../models.js";
+export function createClient(options) {
+    return bind(new Transport(options));
+}
+export function bind(transport) {
+    return {
+        delete: (request, options) => transport.send(DeleteOperation, request, options),
+        get: (request, options) => transport.send(GetOperation, request, options),
+        list: (request, options) => transport.send(ListOperation, request, options),
+        verify: (request, options) => transport.send(VerifyOperation, request, options),
+    };
+}
+const DeleteOperation = {
+    method: "DELETE",
+    route: "/v1/axxa/connections/{id}",
+    body: "nested",
+    response: null,
+    errors: { "400": true, "401": true, "403": true, "404": true, "405": true, "409": true, "413": true, "415": true, "428": true, "429": true, "500": true, "502": true, "503": true, "504": true },
+};
+const GetOperation = {
+    method: "GET",
+    route: "/v1/axxa/connections/{id}",
+    response: object([["data", null, () => ConnectionCodec]]),
+    errors: { "400": true, "401": true, "403": true, "404": true, "405": true, "409": true, "413": true, "415": true, "428": true, "429": true, "500": true, "502": true, "503": true, "504": true },
+};
+const ListOperation = {
+    method: "GET",
+    route: "/v1/axxa/connections",
+    query: { cursor: "cursor", direction: "direction", limit: "limit" },
+    response: object([["data", null, () => ConnectionPageCodec]]),
+    errors: { "400": true, "401": true, "403": true, "404": true, "405": true, "409": true, "413": true, "415": true, "428": true, "429": true, "500": true, "502": true, "503": true, "504": true },
+};
+const VerifyOperation = {
+    method: "POST",
+    route: "/v1/axxa/connections/{connectionId}/verify",
+    body: "flat",
+    response: null,
+    errors: { "400": true, "401": true, "403": true, "404": true, "405": true, "409": true, "413": true, "415": true, "428": true, "429": true, "500": true, "502": true, "503": true, "504": true },
+};

package/dist/axxa/connections/index.d.ts

@@ -0,0 +1,4 @@
+export { ApiError } from "../../_/index.js";
+export type { RequestOptions } from "../../_/index.js";
+export { createClient } from "./client.js";
+export type { Client, ClientOptions, DeleteRequest, DeleteResponse, GetRequest, GetResponse, ListRequest, ListResponse, VerifyRequest, VerifyResponse, } from "./client.js";

package/dist/axxa/connections/index.js

@@ -0,0 +1,4 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+export { ApiError } from "../../_/index.js";
+export { createClient } from "./client.js";

package/dist/axxa/eligibility/client.d.ts

@@ -0,0 +1,44 @@
+import { type BaseClientOptions, type RequestOptions, Transport } from "../../_/index.js";
+import type { ResponseMetadata } from "../../models.js";
+export interface ClientOptions extends BaseClientOptions {
+    /**
+     * The URL the paths of the API are relative to.
+     */
+    baseUrl: string;
+}
+export interface Client {
+    /**
+     * Look up beneficiary eligibility
+     *
+     * Read the plans or affiliation validation messages for a document and
+     * service category. Plans do not establish coverage for a specific CUPS,
+     * authorization, or voucher amount.
+     */
+    lookup(request: LookupRequest, options?: RequestOptions): Promise<LookupResponse>;
+}
+export declare function createClient(options: ClientOptions): Client;
+export declare function bind(transport: Transport): Client;
+export interface LookupRequest {
+    connectionId?: string;
+    documentNumber: string;
+    documentType: "CC" | "CE" | "TI" | "RC" | "PA";
+    serviceType: "outpatient" | "emergency" | "laboratory" | "therapy" | "radiology" | "other";
+}
+export interface LookupResponse {
+    /**
+     * Observed plan/validation result for this service category. This does not
+     * establish coverage for a CUPS, active authorization, or a voucher amount.
+     */
+    data: {
+        plans: {
+            contractNumber: string;
+            name: string;
+            notice: string | null;
+        }[];
+        status: "plans_found" | "validation_required";
+        validationMessages: string[];
+    };
+    error: null;
+    metadata: ResponseMetadata;
+    success: true;
+}

package/dist/axxa/eligibility/client.js

@@ -0,0 +1,18 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+import { Transport, } from "../../_/index.js";
+export function createClient(options) {
+    return bind(new Transport(options));
+}
+export function bind(transport) {
+    return {
+        lookup: (request, options) => transport.send(LookupOperation, request, options),
+    };
+}
+const LookupOperation = {
+    method: "POST",
+    route: "/v1/axxa/eligibility/lookup",
+    body: "flat",
+    response: null,
+    errors: { "400": true, "401": true, "403": true, "404": true, "405": true, "409": true, "413": true, "415": true, "428": true, "429": true, "500": true, "502": true, "503": true, "504": true },
+};

package/dist/axxa/eligibility/index.d.ts

@@ -0,0 +1,4 @@
+export { ApiError } from "../../_/index.js";
+export type { RequestOptions } from "../../_/index.js";
+export { createClient } from "./client.js";
+export type { Client, ClientOptions, LookupRequest, LookupResponse, } from "./client.js";

package/dist/axxa/eligibility/index.js

@@ -0,0 +1,4 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+export { ApiError } from "../../_/index.js";
+export { createClient } from "./client.js";

package/dist/axxa/index.d.ts

@@ -0,0 +1,5 @@
+export { ApiError } from "../_/index.js";
+export type { RequestOptions } from "../_/index.js";
+export { createClient } from "./client.js";
+export type { Client, ClientOptions, } from "./client.js";
+export type { AxxaFailureResponse } from "./models.js";

package/dist/axxa/index.js

@@ -0,0 +1,4 @@
+// Code generated by forge. DO NOT EDIT.
+/* eslint-disable */
+export { ApiError } from "../_/index.js";
+export { createClient } from "./client.js";