@aexhq/sdk 0.46.5-canary → 0.50.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 aex contributors
+
+   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/NOTICE

@@ -0,0 +1,38 @@
+aex
+Copyright 2026 aex contributors
+
+This product includes software developed by the aex project
+(https://github.com/aexhq/aex).
+
+Licensed under the Apache License, Version 2.0. The full text is in LICENSE.
+
+--------------------------------------------------------------------------------
+Third-party software redistributed in published artifacts
+--------------------------------------------------------------------------------
+
+Zod (`zod`)
+Copyright (c) 2025 Colin McDonnell
+Licensed under the MIT License:
+
+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.
+
+`scripts/validate/package-metadata.test.ts` asserts that every production
+dependency of every publishable package in this repository appears above. Adding
+a runtime dependency to a published package without recording it here fails that
+gate.

package/README.md

@@ -1,48 +1,40 @@
 # @aexhq/sdk
 
-The TypeScript SDK and bundled CLI for durable aex agent sessions.
+The TypeScript SDK for explicit aex v1 sessions.
 
 ```bash
 npm i @aexhq/sdk
 ```
 
-Model access is managed: name a model by its `creator/model` gateway slug and
-the platform's key routes it. You supply no provider API key.
-
 ```ts
 import { Aex } from "@aexhq/sdk";
 
-const aex = new Aex(process.env.AEX_API_KEY!);
-const session = await aex.sessions.create({
-  model: "anthropic/claude-haiku-4-5"
-});
-
-const result = await session.messages.send("Summarize this repository.").finished();
-console.log(result.status, result.text, result.costUsd);
-
-const resumed = await aex.sessions.open(session.id);
-console.log(resumed.record.acceptsMessages, resumed.record.lastRun);
+const aex = new Aex(process.env.AEX_WORKSPACE_API_KEY!);
+const runs = await aex.sessions.sessionRunsList({ sessionId: "ses_…" });
+console.log(runs);
 ```
 
-The public surface is organized by ownership:
+The SDK exposes explicit bootstrap resources (`account`, `organizations`,
+`workspaces`, `apiKeys`, and `billing`) and region-pinned workspace resources
+(`sessions`, operations, files, registries, secrets, approvals, telemetry, and
+usage). Long-running mutations return durable operation handles.
 
-- `aex.sessions`: create, reopen, get, list, and delete sessions.
-- `session.messages`, `session.events`, `session.files`: stable session-owned resources.
-- `aex.workspace.files`, `.skills`, `.tools`, `.instructions`, `.secrets`: reusable workspace resources.
-- `aex.start()`: the one-shot create, send, and finish convenience.
+Every resource method is generated from the published contract, one per
+operation the platform serves. An operation the contract declares and nothing
+serves yet has **no method**: a method that could only ever fail would put the
+platform's answer in the client, where it goes stale the day the route lands.
+`ROUTES` still carries all of them with a `deferred` flag, and
+`aex.execute(routeId, …)` stays total over every route id, so a deferred
+operation remains callable by anyone who wants to see the `501` for themselves.
 
-Session submissions accept immutable pinned refs under `assets`, with builtin
-capabilities configured separately through `builtinTools`. A successful
-`RUN_FINISHED` is the consistency boundary: checkpointed files, usage, cost,
-messages, and session state are committed before `finished()` resolves.
+The SDK exposes only the strict v1 resource model. Registered inputs are
+overwrite-by-name resources whose PUT result reports `created`, `replaced`, or
+`unchanged`. Returned byte-bearing values contain checksum/size descriptors,
+never inline bytes or upload IDs. Persisted/live file reads, current registered
+file downloads, and telemetry exports remain explicit.
 
-See the [Quickstart](docs/quickstart.md), [Events](docs/events.md),
-[Files](docs/files.md), and [Composition](docs/concepts/composition.md) guides.
-Runnable projects are collected in
-[`aexhq/examples`](https://github.com/aexhq/examples).
+The native `aex` command is distributed as a signed platform archive.
 
-The package also includes the CLI:
+## License
 
-```bash
-npx aex --help
-```
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/dist/client/aex.d.ts

@@ -0,0 +1,33 @@
+import { type AexTransport } from "../transport/transport.js";
+import { type RouteId } from "../generated/routes.js";
+import { GeneratedResources, type ExecuteOptions } from "../generated/resources.js";
+export interface AexOptions {
+    readonly apiKey: string;
+    readonly centralBaseUrl?: string;
+    readonly regionalBaseUrl?: string;
+    readonly workspaceId?: string;
+    readonly transport?: AexTransport;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly signal?: AbortSignal;
+}
+/**
+ * The client.
+ *
+ * The resource namespaces come from `GeneratedResources`, which the contract
+ * generator writes: one method per served operation, and none for an operation
+ * the platform does not answer. `execute` stays total over `RouteId`, so a
+ * deferred or streaming operation is still callable by anyone who wants to see
+ * what the platform actually says.
+ */
+export declare class Aex extends GeneratedResources {
+    #private;
+    readonly transport: AexTransport;
+    constructor(apiKey: string, options?: Omit<AexOptions, "apiKey">);
+    constructor(options: AexOptions);
+    execute<T>(routeId: RouteId, bindings?: Readonly<Record<string, string>>, options?: ExecuteOptions): Promise<T>;
+    static buildInfo(): Readonly<{
+        packageVersion: string;
+        contractDigest: string;
+        sourceSha: string;
+    }>;
+}

package/dist/client/aex.js

@@ -0,0 +1,98 @@
+import { parseCredential } from "./credentials.js";
+import { resolveCentralBaseUrl, resolveRegionalBaseUrl } from "./routing.js";
+import { FetchTransport } from "../transport/transport.js";
+import { CONTRACT_DIGEST, ROUTES } from "../generated/routes.js";
+import { GeneratedResources } from "../generated/resources.js";
+/**
+ * The client.
+ *
+ * The resource namespaces come from `GeneratedResources`, which the contract
+ * generator writes: one method per served operation, and none for an operation
+ * the platform does not answer. `execute` stays total over `RouteId`, so a
+ * deferred or streaming operation is still callable by anyone who wants to see
+ * what the platform actually says.
+ */
+export class Aex extends GeneratedResources {
+    transport;
+    #credential;
+    #signal;
+    constructor(apiKeyOrOptions, rest = {}) {
+        super();
+        const options = typeof apiKeyOrOptions === "string"
+            ? { ...rest, apiKey: apiKeyOrOptions }
+            : apiKeyOrOptions;
+        this.#credential = parseCredential(options.apiKey);
+        this.#signal = options.signal;
+        if (options.transport) {
+            this.transport = options.transport;
+        }
+        else {
+            this.transport = new FetchTransport({
+                central: resolveCentralBaseUrl(options.centralBaseUrl),
+                regional: resolveRegionalBaseUrl(this.#credential, options),
+            }, options.fetch);
+        }
+    }
+    async execute(routeId, bindings = {}, options = {}) {
+        const route = ROUTES[routeId];
+        let path = route.path;
+        for (const [name, value] of Object.entries(bindings)) {
+            path = path.replace(`{${name}}`, encodeURIComponent(value));
+        }
+        const query = new URLSearchParams(options.query ?? {}).toString();
+        if (query)
+            path = `${path}?${query}`;
+        const headers = new Headers({
+            authorization: this.#credential.authorizationHeader(),
+            accept: "application/json",
+            "Aex-Client": "aex-sdk/0.50.0",
+        });
+        if (options.idempotencyKey)
+            headers.set("Idempotency-Key", options.idempotencyKey);
+        if (options.operationId)
+            headers.set("Aex-Operation-Id", options.operationId);
+        let bytes;
+        if (options.body !== undefined) {
+            headers.set("content-type", "application/json");
+            bytes = encodeCanonicalJson(options.body);
+        }
+        const request = {
+            routeId,
+            method: route.method,
+            path,
+            headers,
+            ...(bytes ? { body: bytes } : {}),
+            ...(this.#signal ? { signal: this.#signal } : {}),
+        };
+        const response = await this.transport.execute(request);
+        return response.body;
+    }
+    static buildInfo() {
+        return Object.freeze({ packageVersion: "0.50.0", contractDigest: CONTRACT_DIGEST, sourceSha: "development" });
+    }
+}
+/**
+ * Encodes one request body with object members in sorted order.
+ *
+ * The platform derives a replay intent from the bytes it receives, so two calls
+ * a caller believes are identical must serialize identically. Ordering every
+ * object once here is the rule that makes that true; the alternative is a
+ * per-route encoder, which is what this replaced.
+ */
+function encodeCanonicalJson(body) {
+    return new TextEncoder().encode(JSON.stringify(canonical(body)));
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value === null || typeof value !== "object")
+        return value;
+    const ordered = {};
+    for (const key of Object.keys(value).sort()) {
+        const member = value[key];
+        if (member !== undefined)
+            ordered[key] = canonical(member);
+    }
+    return ordered;
+}
+//# sourceMappingURL=aex.js.map

package/dist/client/aex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aex.js","sourceRoot":"","sources":["../../src/client/aex.ts"],"names":[],"mappings":"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"}

package/dist/client/credentials.d.ts

@@ -0,0 +1,25 @@
+export type RegionCode = "use1" | "use2" | "usw2" | "apne1" | "euw1";
+declare abstract class Credential {
+    #private;
+    protected constructor(value: string);
+    authorizationHeader(): string;
+    redacted(): string;
+    toJSON(): string;
+}
+export declare class WorkspaceApiKey extends Credential {
+    #private;
+    private constructor();
+    static parse(value: string): WorkspaceApiKey;
+    regionCode(): RegionCode;
+    /** The workspace the key authorizes, as the public prefixed identifier. */
+    workspaceId(): string;
+    regionalBaseUrl(): string;
+}
+export declare class AccountToken extends Credential {
+    private constructor();
+    static parse(value: string): AccountToken;
+}
+export type ParsedCredential = WorkspaceApiKey | AccountToken;
+export declare function parseCredential(value: string): ParsedCredential;
+export declare function regionalHost(region: RegionCode): string;
+export {};

package/dist/client/credentials.js

@@ -0,0 +1,97 @@
+import { AexConfigError } from "../transport/errors.js";
+const BODY = "([0-9a-hjkmnp-tv-z]{26})";
+const SECRET = "([A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])";
+// `aex_wk_<region>_<workspace>_<key>_<secret>`: a workspace key names both the
+// region that serves it and the workspace it authorizes, so a regional endpoint
+// can address every row it must read without a central round trip first.
+const WORKSPACE_KEY = new RegExp(`^aex_wk_(use1|use2|usw2|apne1|euw1)_${BODY}_${BODY}_${SECRET}$`);
+const ACCOUNT_TOKEN = new RegExp(`^aex_at_${BODY}_${SECRET}$`);
+const CROCKFORD = "0123456789abcdefghjkmnpqrstvwxyz";
+const HOSTS = Object.freeze({
+    use1: "https://us-east-1.api.aex.dev",
+    use2: "https://us-east-2.api.aex.dev",
+    usw2: "https://us-west-2.api.aex.dev",
+    apne1: "https://ap-northeast-1.api.aex.dev",
+    euw1: "https://eu-west-1.api.aex.dev",
+});
+class Credential {
+    #value;
+    constructor(value) {
+        this.#value = value;
+    }
+    authorizationHeader() {
+        return `Bearer ${this.#value}`;
+    }
+    redacted() {
+        return `${this.#value.slice(0, this.#value.indexOf("_", 7) + 1)}[redacted]`;
+    }
+    toJSON() {
+        return this.redacted();
+    }
+}
+export class WorkspaceApiKey extends Credential {
+    #region;
+    #workspaceId;
+    constructor(value, region, workspaceId) {
+        super(value);
+        this.#region = region;
+        this.#workspaceId = workspaceId;
+    }
+    static parse(value) {
+        const match = WORKSPACE_KEY.exec(value);
+        if (!match || !isUuid7Body(match[2] ?? "") || !isUuid7Body(match[3] ?? "")) {
+            throw new AexConfigError("invalid credential: expected an aex_wk_ workspace key with UUIDv7 workspace and key ids");
+        }
+        return new WorkspaceApiKey(value, match[1], `wsp_${match[2]}`);
+    }
+    regionCode() {
+        return this.#region;
+    }
+    /** The workspace the key authorizes, as the public prefixed identifier. */
+    workspaceId() {
+        return this.#workspaceId;
+    }
+    regionalBaseUrl() {
+        return HOSTS[this.#region];
+    }
+}
+export class AccountToken extends Credential {
+    constructor(value) {
+        super(value);
+    }
+    static parse(value) {
+        const match = ACCOUNT_TOKEN.exec(value);
+        if (!match || !isUuid7Body(match[1] ?? "")) {
+            throw new AexConfigError("invalid credential: expected an aex_at_ account token");
+        }
+        return new AccountToken(value);
+    }
+}
+export function parseCredential(value) {
+    if (value.startsWith("aex_wk_"))
+        return WorkspaceApiKey.parse(value);
+    if (value.startsWith("aex_at_"))
+        return AccountToken.parse(value);
+    throw new AexConfigError("invalid credential: expected prefix aex_wk_ or aex_at_");
+}
+export function regionalHost(region) {
+    return HOSTS[region];
+}
+function isUuid7Body(body) {
+    let value = 0n;
+    for (const character of body) {
+        const digit = CROCKFORD.indexOf(character);
+        if (digit < 0)
+            return false;
+        value = (value << 5n) | BigInt(digit);
+    }
+    if (value >= (1n << 128n))
+        return false;
+    const bytes = new Uint8Array(16);
+    for (let index = bytes.length - 1; index >= 0; index -= 1) {
+        bytes[index] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    return (bytes[6] & 0xf0) === 0x70 && (bytes[8] & 0xc0) === 0x80;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/client/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/client/credentials.ts"],"names":[],"mappings":"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"}

package/dist/client/routing.d.ts

@@ -0,0 +1,7 @@
+import { type ParsedCredential } from "./credentials.js";
+export interface RegionalRoutingOptions {
+    readonly regionalBaseUrl?: string;
+    readonly workspaceId?: string;
+}
+export declare function resolveRegionalBaseUrl(credential: ParsedCredential, options: RegionalRoutingOptions): string;
+export declare function resolveCentralBaseUrl(value?: string): string;

package/dist/client/routing.js

@@ -0,0 +1,29 @@
+import { AccountToken, WorkspaceApiKey } from "./credentials.js";
+import { AexConfigError } from "../transport/errors.js";
+function validateBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new AexConfigError("base URL must be an absolute HTTPS URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+        throw new AexConfigError("base URL must be HTTPS without credentials, query, or fragment");
+    }
+    return url.toString().replace(/\/$/, "");
+}
+export function resolveRegionalBaseUrl(credential, options) {
+    if (options.regionalBaseUrl)
+        return validateBaseUrl(options.regionalBaseUrl);
+    if (credential instanceof WorkspaceApiKey)
+        return credential.regionalBaseUrl();
+    if (credential instanceof AccountToken && options.workspaceId) {
+        throw new AexConfigError("an account token with workspaceId must resolve placement through workspace_get before regional I/O");
+    }
+    throw new AexConfigError("an account token requires regionalBaseUrl or workspaceId for regional routes");
+}
+export function resolveCentralBaseUrl(value = "https://api.aex.dev") {
+    return validateBaseUrl(value);
+}
+//# sourceMappingURL=routing.js.map

package/dist/client/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/client/routing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAOxD,SAAS,eAAe,CAAC,KAAa;IACpC,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,cAAc,CAAC,wCAAwC,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACxF,MAAM,IAAI,cAAc,CAAC,gEAAgE,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,UAA4B,EAC5B,OAA+B;IAE/B,IAAI,OAAO,CAAC,eAAe;QAAE,OAAO,eAAe,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7E,IAAI,UAAU,YAAY,eAAe;QAAE,OAAO,UAAU,CAAC,eAAe,EAAE,CAAC;IAC/E,IAAI,UAAU,YAAY,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QAC9D,MAAM,IAAI,cAAc,CACtB,oGAAoG,CACrG,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,cAAc,CACtB,8EAA8E,CAC/E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAK,GAAG,qBAAqB;IACjE,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/dist/downloads/download.d.ts

@@ -0,0 +1,25 @@
+export interface DownloadRange {
+    readonly start: number;
+    readonly endExclusive: number;
+}
+export interface DownloadGrant {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly expiresAt: string;
+    readonly sizeBytes: number;
+    readonly authorizedBytes: number;
+    readonly measurementId: string;
+    readonly sha256: string;
+}
+export declare const MAX_SINGLE_GET_BYTES = 5000000000000;
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare function planDownloadRanges(sizeBytes: number, selected?: DownloadRange): readonly DownloadRange[];
+export declare class Download {
+    #private;
+    readonly grant: DownloadGrant;
+    constructor(grant: DownloadGrant, fetchLike?: FetchLike);
+    bytes(): Promise<Uint8Array>;
+    text(): Promise<string>;
+    json<T>(): Promise<T>;
+}
+export {};