@boxrouter/sdk 0.0.0-stage → 0.0.1-alpha.0

package/dist/types.gen.d.ts

@@ -0,0 +1,190 @@
+export type ClientOptions = {
+    baseUrl: `${string}://${string}` | (string & {});
+};
+/**
+ * The provider routes this workspace can use now, one entry per connected account or managed
+ * supply, in the shape `match` reports for an eligible route (its declared gates, resources,
+ * attested facts and lifetime). It lists no route the workspace cannot use, and its
+ * capabilities come from the same adapter declarations `match` reads.
+ *
+ */
+export type ProviderPage = {
+    data: Array<EligibleRoute>;
+};
+/**
+ * One candidate that fits, with the contract it would grant.
+ */
+export type EligibleRoute = {
+    provider: string;
+    class: string | null;
+    account_id: string | null;
+    supply: string;
+    adapter_version: string;
+    gates: {
+        [key: string]: GrantedGate;
+    };
+    resources: {
+        [key: string]: unknown;
+    };
+    attested: {
+        [key: string]: unknown;
+    };
+    lifetime: Lifetime;
+    ranking?: EligibleRouteRanking;
+};
+/**
+ * One gate as granted to this sandbox.
+ */
+export type GrantedGate = {
+    /**
+     * Index into the declaration of route.adapter_version. Only meaningful with that version.
+     */
+    variant: number;
+    /**
+     * The weakest basis among the granted values; for a gate granted with no named knob, the variant's own.
+     */
+    basis: 'implemented' | 'proven';
+    /**
+     * One entry per knob the request named: the granted values for a pick-one knob, the
+     * string "any" where the request said so, the boolean for a yes/no knob, the declared
+     * number for a number knob. This is what the code may rely on.
+     *
+     */
+    granted: {
+        [key: string]: unknown;
+    };
+    /**
+     * The variant's other answers, including declared limits, for information. Calls that depend on them are refused.
+     */
+    also: {
+        [key: string]: unknown;
+    };
+    settings: {
+        [key: string]: unknown;
+    };
+    /**
+     * Set when the account has since lost the gate; that gate's calls then answer gate_unavailable.
+     */
+    unavailable: string | null;
+};
+/**
+ * How long the provider lets the sandbox live. It counts from the provider's create, as
+ * with the provider's own SDK (BoxRouter's clock starts when it sends the create), and the
+ * provider's own timer ends the sandbox (enforcer provider). Whether paused or stopped
+ * time counts depends on the provider.
+ *
+ */
+export type Lifetime = {
+    seconds: number;
+    /**
+     * As of observed_at. Equal to seconds while creating, and frozen while the sandbox is not running.
+     */
+    remaining_seconds: number;
+    /**
+     * Set only while running. The end never comes before it; how soon after is not
+     * promised. The provider's own deadline when ends_at_source is provider. Null while
+     * creating, paused, stopped or ended.
+     *
+     */
+    ends_at: string | null;
+    /**
+     * Whose time ends_at is. provider: the provider's own reported deadline (E2B endAt,
+     * Daytona autoDestroyAt, Blaxel createdAt plus the lifetime). recorded: BoxRouter's
+     * own, the create request's time plus the lifetime. Null when ends_at is null. Cloud
+     * sends it on every lifetime; it is not required only because recorded responses
+     * from before it existed lack it.
+     *
+     */
+    ends_at_source?: 'provider' | 'recorded' | null;
+    /**
+     * While paused or stopped: when the sandbox is destroyed if it is not resumed, 30
+     * days after it last ran, sooner where the provider keeps it for less. A provider
+     * whose own timer keeps counting paused time (Daytona, Blaxel) ends the sandbox when
+     * its lifetime runs out even while paused, so kept_until is that moment when it
+     * falls inside the 30 days; extending the lifetime moves it. Providers that stop the
+     * clock while paused (E2B, Modal, Vercel) keep the full 30 days.
+     *
+     */
+    kept_until: string | null;
+    at_end: 'destroy' | 'pause';
+    /**
+     * Who acts when the time runs out. The hosted API never returns none.
+     */
+    enforcer: 'provider' | 'router' | 'none';
+    /**
+     * The route's longest single run, from one start to the next pause or end, as
+     * narrowed for this account. A declared number: an integer, "unlimited", "unknown"
+     * or a floor.
+     *
+     */
+    max_seconds: number | 'unlimited' | 'unknown' | {
+        at_least: number;
+    };
+    extendable: boolean;
+};
+/**
+ * Why this route sits where it does in the order creation would try, with the price estimate
+ * the order may rest on. It explains the ordering of this dry run; creation re-ranks with the
+ * signals of that moment. Absent on responses from a Cloud that predates it.
+ *
+ */
+export type EligibleRouteRanking = {
+    /**
+     * Place in the order creation would try, 1 first.
+     */
+    position: number;
+    /**
+     * Why the route ranks here. explicit_order is your own provider order; after_named_providers is a provider behind the ones you named; provider_key_order is
+     * a later key of a provider already placed; price_unknown is a managed route with no quote,
+     * tried after routes that have one. New values may appear.
+     *
+     */
+    reason: 'lowest_price' | 'weighted_price' | 'fastest_ready' | 'fastest_run' | 'predicted_completion' | 'predicted_ready_time' | 'explicit_order' | 'after_named_providers' | 'provider_key_order' | 'only_eligible_route' | 'health_deprioritized' | 'latency_preference_missed' | 'price_unknown' | 'no_signals';
+    /**
+     * The reason in one sentence.
+     */
+    explanation: string;
+    /**
+     * What this route would cost per hour at the size it would grant.
+     */
+    estimate: {
+        /**
+         * Null when the size is unknown or the price version has no quote for it.
+         */
+        usd_per_hour: string | null;
+        kind: 'list_estimate' | 'unknown';
+        /**
+         * The size priced and whose price it is, or why there is no estimate.
+         */
+        basis: string;
+    };
+};
+export type ListProvidersData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/providers';
+};
+export type ListProvidersErrors = {
+    /**
+     * Structured error. Unowned and unknown resource IDs both return 404. Admission overload returns 503 with code overloaded, outcome not_started and Retry-After. It reserves no operation and dispatches no provider work. Shared workspace/provider admission budgets return 429 with code rate_limited, outcome not_started and Retry-After. An incomplete request body can return 408 request_timeout before dispatch. Durable-state failures return 503 database_unavailable with outcome unknown; do not infer that execution did not occur. A read (GET or HEAD) that meets the same failure changed nothing: its message says the state is temporarily unavailable, and it is safe to repeat. A provider that cannot be reached when a create is prepared returns 502 provider_error with outcome not_started; nothing was created, and the create can be retried with the same Idempotency-Key or sent to another provider with `providers`.
+     * Native errors are sanitized; upstream credentials, request bodies and
+     * another workspace's metadata are never included. Server-Timing is present only when the response reached Dispatcher or held-response preparation; an earlier response, including pre-Dispatcher admission overload, may omit it.
+     *
+     */
+    401: unknown;
+    /**
+     * Structured error. Unowned and unknown resource IDs both return 404. Admission overload returns 503 with code overloaded, outcome not_started and Retry-After. It reserves no operation and dispatches no provider work. Shared workspace/provider admission budgets return 429 with code rate_limited, outcome not_started and Retry-After. An incomplete request body can return 408 request_timeout before dispatch. Durable-state failures return 503 database_unavailable with outcome unknown; do not infer that execution did not occur. A read (GET or HEAD) that meets the same failure changed nothing: its message says the state is temporarily unavailable, and it is safe to repeat. A provider that cannot be reached when a create is prepared returns 502 provider_error with outcome not_started; nothing was created, and the create can be retried with the same Idempotency-Key or sent to another provider with `providers`.
+     * Native errors are sanitized; upstream credentials, request bodies and
+     * another workspace's metadata are never included. Server-Timing is present only when the response reached Dispatcher or held-response preparation; an earlier response, including pre-Dispatcher admission overload, may omit it.
+     *
+     */
+    default: unknown;
+};
+export type ListProvidersResponses = {
+    /**
+     * Routes available to this workspace.
+     */
+    200: ProviderPage;
+};
+export type ListProvidersResponse = ListProvidersResponses[keyof ListProvidersResponses];

package/dist/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@boxrouter/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-alpha.0",
+  "type": "module",
+  "description": "Early read-only BoxRouter provider discovery client",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  }
+}