@honua/app-platform 0.0.20-alpha.0

package/control-plane/client.d.ts

@@ -0,0 +1,95 @@
+import type { HonuaClient } from "../core/client.js";
+import type { QueryMethod } from "../core/types.js";
+import type { HonuaMapPackage } from "../runtime/index.js";
+import type { StudioCapabilityManifest } from "../studio/capability-manifest.js";
+import { type HonuaApiToken, type HonuaApiTokenCreateRequest, type HonuaCapabilityManifestOptions, type HonuaConnectionSummary, type HonuaControlPlaneCapability, type HonuaControlPlaneJob, type HonuaControlPlaneListOptions, type HonuaControlPlanePage, type HonuaControlPlaneRawRequest, type HonuaControlPlaneRequestOptions, type HonuaControlPlaneResult, type HonuaCreateHostedMapRequest, type HonuaHostedMap, type HonuaHostedMapSummary, type HonuaImportCreateRequest, type HonuaMapPackageSummary, type HonuaPublishMapPackageRequest, type HonuaPublishMapPackageResponse, type HonuaShareRequest, type HonuaShareResponse, type HonuaUpdateHostedMapRequest, type HonuaWorkspaceSummary } from "./types.js";
+export interface HonuaControlPlaneClientOptions {
+    readonly client: HonuaClient;
+    readonly basePath?: string;
+}
+export declare function createHonuaControlPlane(options: HonuaControlPlaneClientOptions): HonuaControlPlaneClient;
+export declare class HonuaControlPlaneClient {
+    #private;
+    readonly hostedMaps: HonuaHostedMapsClient;
+    readonly packages: HonuaMapPackagesClient;
+    readonly imports: HonuaImportsClient;
+    readonly tokens: HonuaApiTokensClient;
+    readonly workspaces: HonuaWorkspacesClient;
+    readonly connections: HonuaConnectionsClient;
+    readonly sharing: HonuaSharingClient;
+    constructor(options: HonuaControlPlaneClientOptions);
+    get basePath(): string;
+    raw<T = unknown>(request: HonuaControlPlaneRawRequest): Promise<HonuaControlPlaneResult<T>>;
+    /**
+     * Fetch the server capability manifest (`honua.capability_manifest.v1`) from
+     * `GET /api/v1/capabilities/manifest`, optionally scoped to an `environment`
+     * and/or `workspaceId`. Lets a client gate UI and tool exposure on what the
+     * connected server actually supports. Returns an unsupported result when the
+     * deployment predates the manifest endpoint (404/501). Mirrors the
+     * honua-sdk-dotnet `HonuaCapabilityManifestClient.GetManifestAsync`.
+     */
+    getCapabilityManifest(options?: HonuaCapabilityManifestOptions): Promise<HonuaControlPlaneResult<StudioCapabilityManifest>>;
+    requestJson<T>(capability: HonuaControlPlaneCapability, method: QueryMethod, path: string, body?: unknown, options?: HonuaControlPlaneRequestOptions & {
+        okStatuses?: readonly number[];
+    }): Promise<HonuaControlPlaneResult<T>>;
+    requestPage<T>(capability: HonuaControlPlaneCapability, path: string, options?: HonuaControlPlaneListOptions): Promise<HonuaControlPlaneResult<HonuaControlPlanePage<T>>>;
+    resolvePath(path: string): string;
+}
+export declare class HonuaHostedMapsClient {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient);
+    list(options?: HonuaControlPlaneListOptions): Promise<HonuaControlPlaneResult<HonuaControlPlanePage<HonuaHostedMapSummary>>>;
+    get(mapId: string, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaHostedMap>>;
+    create(request: HonuaCreateHostedMapRequest, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaHostedMap>>;
+    update(mapId: string, request: HonuaUpdateHostedMapRequest, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaHostedMap>>;
+    getPackage(mapId: string, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaMapPackage>>;
+    getPackageLocator(mapId: string, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<{
+        readonly path: string;
+    }>>;
+}
+export declare class HonuaMapPackagesClient {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient);
+    list(options?: HonuaControlPlaneListOptions): Promise<HonuaControlPlaneResult<HonuaControlPlanePage<HonuaMapPackageSummary>>>;
+    get(packageId: string, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaMapPackage>>;
+    publish(request: HonuaPublishMapPackageRequest, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaPublishMapPackageResponse>>;
+    locator(packageId: string): {
+        readonly path: string;
+    };
+}
+export declare class HonuaImportsClient {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient);
+    listJobs(options?: HonuaControlPlaneListOptions): Promise<HonuaControlPlaneResult<HonuaControlPlanePage<HonuaControlPlaneJob>>>;
+    create(request: HonuaImportCreateRequest, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaControlPlaneJob>>;
+    getJob(jobId: string, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaControlPlaneJob>>;
+    job(jobId: string): HonuaControlPlaneJobHandle;
+}
+export declare class HonuaApiTokensClient {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient);
+    list(options?: HonuaControlPlaneListOptions): Promise<HonuaControlPlaneResult<HonuaControlPlanePage<HonuaApiToken>>>;
+    create(request: HonuaApiTokenCreateRequest, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaApiToken>>;
+    revoke(tokenId: string, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<void>>;
+}
+export declare class HonuaWorkspacesClient {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient);
+    list(options?: HonuaControlPlaneListOptions): Promise<HonuaControlPlaneResult<HonuaControlPlanePage<HonuaWorkspaceSummary>>>;
+}
+export declare class HonuaConnectionsClient {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient);
+    list(options?: HonuaControlPlaneListOptions): Promise<HonuaControlPlaneResult<HonuaControlPlanePage<HonuaConnectionSummary>>>;
+}
+export declare class HonuaSharingClient {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient);
+    updateMapSharing(mapId: string, request: HonuaShareRequest, options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaShareResponse>>;
+}
+export declare class HonuaControlPlaneJobHandle {
+    #private;
+    constructor(controlPlane: HonuaControlPlaneClient, capability: HonuaControlPlaneCapability, path: string);
+    poll(options?: HonuaControlPlaneRequestOptions): Promise<HonuaControlPlaneResult<HonuaControlPlaneJob>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/control-plane/client.d.ts.map

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

package/control-plane/client.js

@@ -0,0 +1,374 @@
+import { honuaCacheValidatorFromHeaders } from "../core/cache-state.js";
+import { HonuaHttpError } from "../core/errors.js";
+import { trimTrailingSlashes } from "../core/path-utils.js";
+import { HONUA_CAPABILITY_MANIFEST_PATH, HONUA_CONTROL_PLANE_BASE_PATH, } from "./types.js";
+export function createHonuaControlPlane(options) {
+    return new HonuaControlPlaneClient(options);
+}
+export class HonuaControlPlaneClient {
+    #client;
+    #basePath;
+    hostedMaps;
+    packages;
+    imports;
+    tokens;
+    workspaces;
+    connections;
+    sharing;
+    constructor(options) {
+        this.#client = options.client;
+        this.#basePath = normalizeBasePath(options.basePath ?? HONUA_CONTROL_PLANE_BASE_PATH);
+        this.hostedMaps = new HonuaHostedMapsClient(this);
+        this.packages = new HonuaMapPackagesClient(this);
+        this.imports = new HonuaImportsClient(this);
+        this.tokens = new HonuaApiTokensClient(this);
+        this.workspaces = new HonuaWorkspacesClient(this);
+        this.connections = new HonuaConnectionsClient(this);
+        this.sharing = new HonuaSharingClient(this);
+    }
+    get basePath() {
+        return this.#basePath;
+    }
+    async raw(request) {
+        return this.requestJson("raw", request.method ?? "GET", request.path, request.body, {
+            signal: request.signal,
+            headers: request.headers,
+            okStatuses: request.okStatuses,
+        });
+    }
+    /**
+     * Fetch the server capability manifest (`honua.capability_manifest.v1`) from
+     * `GET /api/v1/capabilities/manifest`, optionally scoped to an `environment`
+     * and/or `workspaceId`. Lets a client gate UI and tool exposure on what the
+     * connected server actually supports. Returns an unsupported result when the
+     * deployment predates the manifest endpoint (404/501). Mirrors the
+     * honua-sdk-dotnet `HonuaCapabilityManifestClient.GetManifestAsync`.
+     */
+    async getCapabilityManifest(options = {}) {
+        const { environment, workspaceId, ...requestOptions } = options;
+        return this.requestJson("capabilities", "GET", withManifestQuery(HONUA_CAPABILITY_MANIFEST_PATH, environment, workspaceId), undefined, requestOptions);
+    }
+    async requestJson(capability, method, path, body, options = {}) {
+        try {
+            const response = await this.#client.pipelineFetch(method, this.resolvePath(path), {
+                headers: jsonHeaders(options.headers),
+                body: body === undefined ? null : JSON.stringify(body),
+            }, options.signal, options.okStatuses ? { okStatuses: options.okStatuses } : {});
+            if (response.status === 204)
+                return supported(undefined);
+            const value = (await readJson(response));
+            return supported(value);
+        }
+        catch (error) {
+            return unsupportedFromError(capability, error);
+        }
+    }
+    async requestPage(capability, path, options = {}) {
+        try {
+            const hasValidator = Boolean(options.validator?.etag || options.validator?.lastModified);
+            const response = await this.#client.pipelineFetch("GET", this.resolvePath(withListQuery(path, options)), { headers: listHeaders(options) }, options.signal, { okStatuses: hasValidator ? [304, 404, 501] : [404, 501] });
+            if (response.status === 404 || response.status === 501) {
+                return unsupportedFromStatus(capability, response.status, await readJson(response));
+            }
+            const value = normalizePage(response.status === 304 ? undefined : await readJson(response), response, {
+                fallbackValidator: options.validator,
+            });
+            return supported(value);
+        }
+        catch (error) {
+            return unsupportedFromError(capability, error);
+        }
+    }
+    resolvePath(path) {
+        if (path.startsWith("http://") || path.startsWith("https://"))
+            return path;
+        const normalized = path.startsWith("/") ? path : `/${path}`;
+        if (normalized === this.#basePath || normalized.startsWith(`${this.#basePath}/`))
+            return normalized;
+        // Server-wide, already-rooted API paths (e.g. the capability manifest at
+        // /api/v1/capabilities/manifest) are used verbatim rather than nested under
+        // the admin base path.
+        if (normalized.startsWith("/api/"))
+            return normalized;
+        return `${this.#basePath}${normalized}`;
+    }
+}
+export class HonuaHostedMapsClient {
+    #controlPlane;
+    constructor(controlPlane) {
+        this.#controlPlane = controlPlane;
+    }
+    list(options = {}) {
+        return this.#controlPlane.requestPage("hosted-maps", "/maps", options);
+    }
+    get(mapId, options = {}) {
+        return this.#controlPlane.requestJson("hosted-maps", "GET", `/maps/${encodeURIComponent(mapId)}`, undefined, options);
+    }
+    create(request, options = {}) {
+        return this.#controlPlane.requestJson("hosted-maps", "POST", "/maps", request, options);
+    }
+    update(mapId, request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#controlPlane.requestJson("hosted-maps", "PATCH", `/maps/${encodeURIComponent(mapId)}`, body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+    async getPackage(mapId, options = {}) {
+        return this.#controlPlane.requestJson("map-packages", "GET", `/maps/${encodeURIComponent(mapId)}/package`, undefined, options);
+    }
+    async getPackageLocator(mapId, options = {}) {
+        const result = await this.get(mapId, options);
+        if (!result.supported)
+            return result;
+        const href = result.value.links?.mapPackage;
+        return supported({ path: href ?? this.#controlPlane.resolvePath(`/maps/${encodeURIComponent(mapId)}/package`) });
+    }
+}
+export class HonuaMapPackagesClient {
+    #controlPlane;
+    constructor(controlPlane) {
+        this.#controlPlane = controlPlane;
+    }
+    list(options = {}) {
+        return this.#controlPlane.requestPage("map-packages", "/packages", options);
+    }
+    get(packageId, options = {}) {
+        return this.#controlPlane.requestJson("map-packages", "GET", `/packages/${encodeURIComponent(packageId)}`, undefined, options);
+    }
+    publish(request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#controlPlane.requestJson("map-packages", "POST", "/packages", body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+    locator(packageId) {
+        return { path: this.#controlPlane.resolvePath(`/packages/${encodeURIComponent(packageId)}`) };
+    }
+}
+export class HonuaImportsClient {
+    #controlPlane;
+    constructor(controlPlane) {
+        this.#controlPlane = controlPlane;
+    }
+    listJobs(options = {}) {
+        return this.#controlPlane.requestPage("imports", "/imports/jobs", options);
+    }
+    create(request, options = {}) {
+        return this.#controlPlane.requestJson("imports", "POST", "/imports", request, options);
+    }
+    getJob(jobId, options = {}) {
+        return this.#controlPlane.requestJson("imports", "GET", `/imports/jobs/${encodeURIComponent(jobId)}`, undefined, options);
+    }
+    job(jobId) {
+        return new HonuaControlPlaneJobHandle(this.#controlPlane, "imports", `/imports/jobs/${encodeURIComponent(jobId)}`);
+    }
+}
+export class HonuaApiTokensClient {
+    #controlPlane;
+    constructor(controlPlane) {
+        this.#controlPlane = controlPlane;
+    }
+    list(options = {}) {
+        return this.#controlPlane.requestPage("api-tokens", "/tokens", options).then(redactPageResult);
+    }
+    create(request, options = {}) {
+        return this.#controlPlane
+            .requestJson("api-tokens", "POST", "/tokens", request, options)
+            .then(redactTokenResult);
+    }
+    revoke(tokenId, options = {}) {
+        return this.#controlPlane.requestJson("api-tokens", "DELETE", `/tokens/${encodeURIComponent(tokenId)}`, undefined, options);
+    }
+}
+export class HonuaWorkspacesClient {
+    #controlPlane;
+    constructor(controlPlane) {
+        this.#controlPlane = controlPlane;
+    }
+    list(options = {}) {
+        return this.#controlPlane.requestPage("workspaces", "/workspaces", options);
+    }
+}
+export class HonuaConnectionsClient {
+    #controlPlane;
+    constructor(controlPlane) {
+        this.#controlPlane = controlPlane;
+    }
+    list(options = {}) {
+        return this.#controlPlane
+            .requestPage("connections", "/connections", options)
+            .then(redactPageResult);
+    }
+}
+export class HonuaSharingClient {
+    #controlPlane;
+    constructor(controlPlane) {
+        this.#controlPlane = controlPlane;
+    }
+    updateMapSharing(mapId, request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#controlPlane.requestJson("sharing", "PUT", `/maps/${encodeURIComponent(mapId)}/sharing`, body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+}
+export class HonuaControlPlaneJobHandle {
+    #controlPlane;
+    #capability;
+    #path;
+    constructor(controlPlane, capability, path) {
+        this.#controlPlane = controlPlane;
+        this.#capability = capability;
+        this.#path = path;
+    }
+    poll(options = {}) {
+        return this.#controlPlane.requestJson(this.#capability, "GET", this.#path, undefined, options);
+    }
+}
+function supported(value) {
+    return { supported: true, value };
+}
+function unsupportedFromError(capability, error) {
+    if (error instanceof HonuaHttpError && (error.statusCode === 404 || error.statusCode === 501)) {
+        return unsupportedFromStatus(capability, error.statusCode, error.body);
+    }
+    throw error;
+}
+function unsupportedFromStatus(capability, statusCode, body) {
+    const problem = toProblemDetails(body);
+    return {
+        supported: false,
+        capability,
+        statusCode,
+        reason: problem?.detail ??
+            problem?.title ??
+            `Control-plane capability "${capability}" is not exposed by this deployment.`,
+        ...(problem ? { problem } : {}),
+    };
+}
+function normalizeBasePath(path) {
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    return trimTrailingSlashes(normalized);
+}
+function withListQuery(path, options) {
+    const params = new URLSearchParams();
+    if (options.cursor)
+        params.set("cursor", options.cursor);
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    if (options.workspaceId)
+        params.set("workspaceId", options.workspaceId);
+    if (options.q)
+        params.set("q", options.q);
+    if (options.includeDeleted !== undefined)
+        params.set("includeDeleted", String(options.includeDeleted));
+    const query = params.toString();
+    return query ? `${path}${path.includes("?") ? "&" : "?"}${query}` : path;
+}
+function withManifestQuery(path, environment, workspaceId) {
+    const params = new URLSearchParams();
+    if (environment)
+        params.set("environment", environment);
+    if (workspaceId)
+        params.set("workspaceId", workspaceId);
+    const query = params.toString();
+    return query ? `${path}?${query}` : path;
+}
+function jsonHeaders(headers) {
+    return {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...headersToRecord(headers),
+    };
+}
+function listHeaders(options) {
+    const headers = {
+        Accept: "application/json",
+        ...headersToRecord(options.headers),
+    };
+    if (options.validator?.etag)
+        headers["If-None-Match"] = options.validator.etag;
+    if (options.validator?.lastModified)
+        headers["If-Modified-Since"] = options.validator.lastModified;
+    return headers;
+}
+function withIfMatch(headers, ifMatch) {
+    if (!ifMatch)
+        return headers;
+    return { ...headersToRecord(headers), "If-Match": ifMatch };
+}
+function headersToRecord(headers) {
+    if (!headers)
+        return {};
+    if (headers instanceof Headers)
+        return Object.fromEntries(headers.entries());
+    if (Array.isArray(headers))
+        return Object.fromEntries(headers);
+    return { ...headers };
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+function normalizePage(body, response, options = {}) {
+    const value = isRecord(body) ? body : {};
+    const items = (Array.isArray(value.items) ? value.items : Array.isArray(value.data) ? value.data : []);
+    const pagination = isRecord(value.pagination) ? value.pagination : value;
+    const validator = honuaCacheValidatorFromHeaders(response.headers) ?? options.fallbackValidator;
+    const sourceUpdatedAt = response.headers.get("last-modified") ?? undefined;
+    return {
+        items,
+        pagination: {
+            nextCursor: stringValue(pagination.nextCursor ?? pagination.next),
+            previousCursor: stringValue(pagination.previousCursor ?? pagination.previous),
+            limit: numberValue(pagination.limit),
+            total: numberValue(pagination.total),
+        },
+        ...(validator ? { validator } : {}),
+        ...(sourceUpdatedAt ? { sourceUpdatedAt } : {}),
+    };
+}
+function toProblemDetails(body) {
+    if (!isRecord(body))
+        return undefined;
+    const candidate = isRecord(body.problem) ? body.problem : body;
+    return candidate;
+}
+function redactPageResult(result) {
+    if (!result.supported)
+        return result;
+    return {
+        supported: true,
+        value: {
+            ...result.value,
+            items: result.value.items.map(redactSecrets),
+        },
+    };
+}
+function redactTokenResult(result) {
+    if (!result.supported)
+        return result;
+    return { supported: true, value: redactSecrets(result.value) };
+}
+function redactSecrets(value) {
+    const out = { ...value };
+    for (const key of ["value", "secret", "password", "token"]) {
+        if (typeof out[key] === "string")
+            out[key] = "[REDACTED]";
+    }
+    return out;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}

package/control-plane/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Experimental hosted-product/control-plane client.
+ *
+ * Runtime data operations stay on `HonuaClient` and `@honua/sdk-js/runtime`.
+ * This subpath owns admin resources such as hosted maps, packages, imports,
+ * tokens, workspaces, connections, and sharing, with typed handoff through
+ * MapPackage locators and SourceDescriptor-compatible shapes.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { HonuaApiTokensClient, HonuaConnectionsClient, HonuaControlPlaneClient, HonuaControlPlaneJobHandle, HonuaHostedMapsClient, HonuaImportsClient, HonuaMapPackagesClient, HonuaSharingClient, HonuaWorkspacesClient, createHonuaControlPlane, } from "./client.js";
+export type { HonuaControlPlaneClientOptions } from "./client.js";
+export type { StudioCapabilityManifest } from "../studio/capability-manifest.js";
+export { HONUA_CAPABILITY_MANIFEST_PATH, HONUA_CONTROL_PLANE_BASE_PATH } from "./types.js";
+export type { HonuaApiToken, HonuaApiTokenCreateRequest, HonuaCapabilityManifestOptions, HonuaConnectionSummary, HonuaControlPlaneCapability, HonuaControlPlaneJob, HonuaControlPlaneJobStatus, HonuaControlPlaneLinks, HonuaControlPlaneListOptions, HonuaControlPlanePage, HonuaControlPlaneRawRequest, HonuaControlPlaneRequestOptions, HonuaControlPlaneResult, HonuaControlPlaneSourceDescriptor, HonuaControlPlaneSuccess, HonuaControlPlaneUnsupported, HonuaCreateHostedMapRequest, HonuaEntityValidators, HonuaHostedMap, HonuaHostedMapSummary, HonuaImportCreateRequest, HonuaMapPackageSummary, HonuaProblemDetails, HonuaPublishMapPackageRequest, HonuaPublishMapPackageResponse, HonuaShareRequest, HonuaShareResponse, HonuaUpdateHostedMapRequest, HonuaWorkspaceSummary, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/control-plane/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/control-plane/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAC3F,YAAY,EACV,aAAa,EACb,0BAA0B,EAC1B,8BAA8B,EAC9B,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,qBAAqB,EACrB,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,EACvB,iCAAiC,EACjC,wBAAwB,EACxB,4BAA4B,EAC5B,2BAA2B,EAC3B,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACnB,6BAA6B,EAC7B,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/control-plane/index.js

@@ -0,0 +1,14 @@
+/**
+ * Experimental hosted-product/control-plane client.
+ *
+ * Runtime data operations stay on `HonuaClient` and `@honua/sdk-js/runtime`.
+ * This subpath owns admin resources such as hosted maps, packages, imports,
+ * tokens, workspaces, connections, and sharing, with typed handoff through
+ * MapPackage locators and SourceDescriptor-compatible shapes.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { HonuaApiTokensClient, HonuaConnectionsClient, HonuaControlPlaneClient, HonuaControlPlaneJobHandle, HonuaHostedMapsClient, HonuaImportsClient, HonuaMapPackagesClient, HonuaSharingClient, HonuaWorkspacesClient, createHonuaControlPlane, } from "./client.js";
+export { HONUA_CAPABILITY_MANIFEST_PATH, HONUA_CONTROL_PLANE_BASE_PATH } from "./types.js";