@seta-labs/proxy 0.0.0-stage → 0.1.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @seta-labs/proxy
+
+## 0.1.0-next.0
+
+- Initial public package preparation, compatible with the Seta Proxy 0.13.5 HTTP
+  contract: application lease/catalog client and separate administration entry.
+- Typed inputs/results, Fetch injection, cancellation and HTTP error metadata;
+  no automatic retries or relay/provider policy.
+- Self-contained ESM declarations and same-origin panel integration.
+
+This version has not been published by the implementation work.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @seta-labs/proxy
 
-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.
+ESM, browser-safe TypeScript client for Seta Proxy's control plane. The package
+contains no relay/CONNECT implementation, proxy agent, provider SDK, `call-pool`,
+queue, retry, timeout policy or runtime environment configuration.
+
+```ts
+import { ApiError, createProxyClient } from '@seta-labs/proxy';
+
+const proxy = createProxyClient({
+    baseUrl: 'https://proxy.example/api',
+    apiKey: applicationKey,
+});
+const lease = await proxy.leases.create(
+    { gateway: 'default', targetHost: 'example.com' },
+    { signal: AbortSignal.timeout(20_000) },
+);
+await proxy.leases.release(lease.id);
+```
+
+`baseUrl` is the absolute API root **including `/api`**, with an optional trailing
+slash. Relative URLs, embedded credentials, queries and fragments are rejected.
+On a panel use `new URL('/api', requestOrWindowUrl).href` and omit `apiKey`; the
+same-origin backend supplies the key. Never embed an operator key in browser
+code. Make a client per SSR request and forward only the authentication headers
+that backend needs; do not share user cookies between requests.
+
+`fetch` is injectable and must accept a standard `Request` and return a standard
+`Response`. A body-returning `$fetch` is not compatible. `headers` are copied per
+client; `apiKey` takes precedence over an `x-api-key` supplied there. Optional
+`credentials` has Fetch semantics. Every method takes optional `{ signal }` last.
+
+Application methods:
+
+- `gateways.list(options?)`
+- `leases.create(input, options?)`, `get(id, options?)`, `renew(id, options?)`
+- `leases.release(id, options?)`, `report(id, input, options?)`
+
+Administration uses a separate entry point and an operator key on the backend:
+
+```ts
+import { createProxyAdminClient } from '@seta-labs/proxy/admin';
+const admin = createProxyAdminClient({ baseUrl: apiRoot, apiKey: operatorKey });
+const accounts = await admin.providers.list();
+```
+
+Admin methods mirror the current management contract:
+
+- `apiKeys.list`, `create`, `revoke`
+- `endpoints.list`, `update`, `check`, `checkAll`
+- `providers.list`, `get`, `create`, `update`, `pause`, `resume`, `disconnect`,
+  `test`, `sync`, `resources`, `runs`
+- `gateways.list`, `create`, `update`, `remove`, `addMember`, `removeMember`
+- `bans.list`, `byEndpoint`; `report`, `stats`, `refresh`, `syncIproyal`
+- `playground.config`, `run`
+
+All 38 functional operations are covered. The three health operations are
+intentionally excluded. Import separation is convenience; server guards enforce
+permissions. Calling the wrong API with a key still produces the server's 401/403.
+
+Methods return `Promise<T>` using types derived from the server OpenAPI contract.
+This is compile-time typing, not runtime payload validation. Retain consumer
+validation and domain policy. Empty successful responses, including 204, resolve
+to `undefined` on the void release/report/remove methods. Empty responses where
+the contract expects data and malformed success JSON throw `ResponseParseError` with
+status, headers, body and cause. Network errors and abort reasons pass through.
+
+Every HTTP failure throws `ApiError`: `status`, `statusText`, a copied `headers`,
+untrusted `body` (parsed JSON or original text), and `requestId` (header first,
+then body). Inspect `body` safely before using domain codes or `retryAfterMs`;
+`headers.get('retry-after')` is retained. No error bodies or credentials are
+logged by this package. No method retries automatically, including lease creation
+and provider sync. A connection failure after a write may be ambiguous: the
+consumer decides how to recover. Lease 404/410, revoked keys, 429 and 503 remain
+HTTP errors, never silently converted to expired leases or waits.
+
+Supported runtime: Node.js 22+ with native Fetch, and browsers with Fetch,
+Request, Response, Headers and AbortController. TypeScript declarations are
+self-contained; the private `@seta-proxy/types` workspace is not a consumer
+dependency. The repository gate uses Node 26; tarball smoke also runs on Node 22.
+The first prerelease targets the HTTP contract of Seta Proxy `0.13.5`.
+
+## Packaging and release
+
+`pnpm sdk:pack` builds and packs locally; `pnpm sdk:smoke` packs to an external
+temporary directory, inspects the allowlist, installs the tarball without
+workspace links, checks runtime imports and compiles public types with library
+checking enabled. Neither command publishes.
+
+Versions are independent of the application. The SDK stays on `0.x` until the
+owner explicitly authorizes graduation to `1.0`; stabilization does not imply
+that approval. Use Changesets for SDK and exposed contract changes, documenting
+compatibility and migration requirements for each `0.x` release. The prepared
+initial version is `0.1.0-next.0` (`next`). Each later release documents the minimum compatible server;
+publishing a package never deploys that server. Keep `publishConfig.tag` aligned
+when exiting prerelease mode; the workflow explicitly selects `next` or `latest`
+from the version.
+
+The dedicated `publish-sdk.yml` accepts only `@seta-labs/proxy@<version>` tags,
+requires successful application CI on the exact tagged commit, checks tag/manifest
+equality, runs SDK/type checks and tarball smoke, then uses
+npm OIDC on a GitHub-hosted runner. `v*` image release tags are unchanged.
+Before tagging, obtain successful repository `code:check` and `test:unit` results
+(the ordinary CI runs these too), plus required API e2e checks in an authorized
+environment. The npm workflow adds no DB or runtime environment variables.
+
+Operator prerequisites, not configured by this change: confirm scope ownership
+and name availability, approve the license, bootstrap the package if npm requires
+it, and configure its npm trusted publisher for `Seta-Labs/seta-proxy` and
+`publish-sdk.yml` with **direct publishing** enabled. No npm token is added.
+Source repository visibility is independent from public package visibility;
+provenance is disabled for compatibility with private source repositories.
+The manifest currently retains `UNLICENSED` rather than granting a new license.
+Never overwrite published versions: rollback a consumer lockfile or publish a
+new version and deprecate the defective one. Publication remains an explicit
+operator action. [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).

package/dist/admin.d.ts

@@ -0,0 +1,54 @@
+import { R as RequestOptions, A as ApiKey, C as CreateApiKeyInput, I as IssuedApiKey, P as ProxyEndpoint, U as UpdateEndpointInput, E as EndpointCheckResult, a as ProviderAccount, b as ProviderAccountInput, c as ProviderAccountPatch, d as ProviderSyncResult, S as SyncProviderAccountInput, e as ProviderResource, f as ProviderSyncRun, g as ProxyGateway, h as CreateGatewayInput, i as UpdateGatewayInput, G as GatewayMemberInput, B as BanQuery, j as ProxyBanEvent, k as EndpointBanSummary, l as PlaygroundConfigRequest, m as PlaygroundConfig, n as PlaygroundRunRequest, o as PlaygroundRunResult, p as ReportBanRequest, q as ReportBanResponse, r as RelayStats, s as RefreshResult, t as SyncIproyalRequest, u as SyncIproyalResponse, v as ProxyClientOptions } from './transport-CWjoRf8k.js';
+export { w as ApiError, x as ResponseParseError } from './transport-CWjoRf8k.js';
+
+interface ProxyAdminClient {
+    apiKeys: {
+        list(options?: RequestOptions): Promise<ApiKey[]>;
+        create(input: CreateApiKeyInput, options?: RequestOptions): Promise<IssuedApiKey>;
+        revoke(id: string, options?: RequestOptions): Promise<ApiKey>;
+    };
+    endpoints: {
+        list(options?: RequestOptions): Promise<ProxyEndpoint[]>;
+        update(id: string, input: UpdateEndpointInput, options?: RequestOptions): Promise<ProxyEndpoint>;
+        check(id: string, options?: RequestOptions): Promise<EndpointCheckResult>;
+        checkAll(options?: RequestOptions): Promise<EndpointCheckResult[]>;
+    };
+    providers: {
+        list(options?: RequestOptions): Promise<ProviderAccount[]>;
+        get(id: string, options?: RequestOptions): Promise<ProviderAccount>;
+        create(input: ProviderAccountInput, options?: RequestOptions): Promise<ProviderAccount>;
+        update(id: string, input: ProviderAccountPatch, options?: RequestOptions): Promise<ProviderAccount>;
+        pause(id: string, options?: RequestOptions): Promise<ProviderAccount>;
+        resume(id: string, options?: RequestOptions): Promise<ProviderAccount>;
+        disconnect(id: string, options?: RequestOptions): Promise<ProviderAccount>;
+        test(id: string, options?: RequestOptions): Promise<ProviderSyncResult>;
+        sync(id: string, input: SyncProviderAccountInput, options?: RequestOptions): Promise<ProviderSyncResult>;
+        resources(id: string, options?: RequestOptions): Promise<ProviderResource[]>;
+        runs(id: string, options?: RequestOptions): Promise<ProviderSyncRun[]>;
+    };
+    gateways: {
+        list(options?: RequestOptions): Promise<ProxyGateway[]>;
+        create(input: CreateGatewayInput, options?: RequestOptions): Promise<ProxyGateway>;
+        update(id: string, input: UpdateGatewayInput, options?: RequestOptions): Promise<ProxyGateway>;
+        remove(id: string, options?: RequestOptions): Promise<void>;
+        addMember(id: string, input: GatewayMemberInput, options?: RequestOptions): Promise<ProxyGateway>;
+        removeMember(id: string, endpointId: string, options?: RequestOptions): Promise<ProxyGateway>;
+    };
+    bans: {
+        list(query?: BanQuery, options?: RequestOptions): Promise<ProxyBanEvent[]>;
+        byEndpoint(options?: RequestOptions): Promise<EndpointBanSummary[]>;
+    };
+    playground: {
+        config(input: PlaygroundConfigRequest, options?: RequestOptions): Promise<PlaygroundConfig[]>;
+        run(input: PlaygroundRunRequest, options?: RequestOptions): Promise<PlaygroundRunResult>;
+    };
+    report(input: ReportBanRequest, options?: RequestOptions): Promise<ReportBanResponse>;
+    stats(options?: RequestOptions): Promise<RelayStats>;
+    refresh(options?: RequestOptions): Promise<RefreshResult>;
+    syncIproyal(input: SyncIproyalRequest, options?: RequestOptions): Promise<SyncIproyalResponse>;
+}
+/** Management control plane. Keep the operator key on your server. */
+declare function createProxyAdminClient(options: ProxyClientOptions): ProxyAdminClient;
+
+export { ApiKey, BanQuery, CreateApiKeyInput, CreateGatewayInput, EndpointBanSummary, EndpointCheckResult, GatewayMemberInput, IssuedApiKey, PlaygroundConfig, PlaygroundConfigRequest, PlaygroundRunRequest, PlaygroundRunResult, ProviderAccount, ProviderAccountInput, ProviderAccountPatch, ProviderResource, ProviderSyncResult, ProviderSyncRun, ProxyBanEvent, ProxyClientOptions, ProxyEndpoint, ProxyGateway, RefreshResult, RelayStats, ReportBanRequest, ReportBanResponse, RequestOptions, SyncIproyalRequest, SyncIproyalResponse, SyncProviderAccountInput, UpdateEndpointInput, UpdateGatewayInput, createProxyAdminClient };
+export type { ProxyAdminClient };

package/dist/admin.js

@@ -0,0 +1,169 @@
+import {
+  ApiError,
+  ResponseParseError,
+  createTransport,
+  result,
+  textOptions
+} from "./chunk-6QCKYRE3.js";
+
+// src/admin.ts
+function createProxyAdminClient(options) {
+  const http = createTransport(options);
+  return {
+    apiKeys: apiKeysMethods(http),
+    endpoints: endpointsMethods(http),
+    providers: providersMethods(http),
+    gateways: gatewaysMethods(http),
+    bans: bansMethods(http),
+    playground: playgroundMethods(http),
+    report: (input, options2) => result(http.POST("/proxies/report", { ...textOptions(options2), body: input })),
+    stats: (options2) => result(http.GET("/proxies/stats", { ...textOptions(options2) })),
+    refresh: (options2) => result(http.POST("/proxies/refresh", { ...textOptions(options2) })),
+    syncIproyal: (input, options2) => result(http.POST("/proxies/sync/iproyal", { ...textOptions(options2), body: input }))
+  };
+}
+function apiKeysMethods(http) {
+  return {
+    list: (options) => result(http.GET("/proxies/api-keys", { ...textOptions(options) })),
+    create: (input, options) => result(http.POST("/proxies/api-keys", { ...textOptions(options), body: input })),
+    revoke: (id, options) => result(
+      http.DELETE("/proxies/api-keys/{id}", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    )
+  };
+}
+function endpointsMethods(http) {
+  return {
+    list: (options) => result(http.GET("/proxies/endpoints", { ...textOptions(options) })),
+    update: (id, input, options) => result(
+      http.PATCH("/proxies/endpoints/{id}", {
+        ...textOptions(options),
+        params: { path: { id } },
+        body: input
+      })
+    ),
+    check: (id, options) => result(
+      http.POST("/proxies/endpoints/{id}/check", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    ),
+    checkAll: (options) => result(http.POST("/proxies/endpoints/check-all", { ...textOptions(options) }))
+  };
+}
+function providersMethods(http) {
+  return {
+    list: (options) => result(http.GET("/proxies/providers", { ...textOptions(options) })),
+    get: (id, options) => result(
+      http.GET("/proxies/providers/{id}", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    ),
+    create: (input, options) => result(http.POST("/proxies/providers", { ...textOptions(options), body: input })),
+    update: (id, input, options) => result(
+      http.PATCH("/proxies/providers/{id}", {
+        ...textOptions(options),
+        params: { path: { id } },
+        body: input
+      })
+    ),
+    pause: (id, options) => result(
+      http.POST("/proxies/providers/{id}/pause", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    ),
+    resume: (id, options) => result(
+      http.POST("/proxies/providers/{id}/resume", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    ),
+    disconnect: (id, options) => result(
+      http.POST("/proxies/providers/{id}/disconnect", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    ),
+    test: (id, options) => result(
+      http.POST("/proxies/providers/{id}/test", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    ),
+    sync: (id, input, options) => result(
+      http.POST("/proxies/providers/{id}/sync", {
+        ...textOptions(options),
+        params: { path: { id } },
+        body: input
+      })
+    ),
+    resources: (id, options) => result(
+      http.GET("/proxies/providers/{id}/resources", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    ),
+    runs: (id, options) => result(
+      http.GET("/proxies/providers/{id}/runs", {
+        ...textOptions(options),
+        params: { path: { id } }
+      })
+    )
+  };
+}
+function gatewaysMethods(http) {
+  return {
+    list: (options) => result(http.GET("/proxies/gateways", { ...textOptions(options) })),
+    create: (input, options) => result(http.POST("/proxies/gateways", { ...textOptions(options), body: input })),
+    update: (id, input, options) => result(
+      http.PATCH("/proxies/gateways/{id}", {
+        ...textOptions(options),
+        params: { path: { id } },
+        body: input
+      })
+    ),
+    remove: (id, options) => result(
+      http.DELETE("/proxies/gateways/{id}", {
+        ...textOptions(options),
+        params: { path: { id } }
+      }),
+      true
+    ),
+    addMember: (id, input, options) => result(
+      http.POST("/proxies/gateways/{id}/members", {
+        ...textOptions(options),
+        params: { path: { id } },
+        body: input
+      })
+    ),
+    removeMember: (id, endpointId, options) => result(
+      http.DELETE("/proxies/gateways/{id}/members/{endpointId}", {
+        ...textOptions(options),
+        params: { path: { id, endpointId } }
+      })
+    )
+  };
+}
+function bansMethods(http) {
+  return {
+    list: (query, options) => result(http.GET("/proxies/bans", { ...textOptions(options), params: { query } })),
+    byEndpoint: (options) => result(http.GET("/proxies/bans/by-endpoint", { ...textOptions(options) }))
+  };
+}
+function playgroundMethods(http) {
+  return {
+    config: (input, options) => result(
+      http.POST("/proxies/playground/config", { ...textOptions(options), body: input })
+    ),
+    run: (input, options) => result(http.POST("/proxies/playground/run", { ...textOptions(options), body: input }))
+  };
+}
+export {
+  ApiError,
+  ResponseParseError,
+  createProxyAdminClient
+};

package/dist/chunk-6QCKYRE3.js

@@ -0,0 +1,81 @@
+// src/transport.ts
+import createClient from "openapi-fetch";
+var ApiError = class extends Error {
+  status;
+  statusText;
+  headers;
+  body;
+  requestId;
+  constructor(response, body) {
+    super(`Proxy API request failed with HTTP ${response.status}`);
+    this.name = "ApiError";
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.headers = new Headers(response.headers);
+    this.body = body;
+    this.requestId = response.headers.get("x-request-id") ?? bodyRequestId(body);
+  }
+};
+var ResponseParseError = class extends Error {
+  status;
+  headers;
+  body;
+  constructor(response, body, cause) {
+    super("Proxy API returned invalid JSON", { cause });
+    this.name = "ResponseParseError";
+    this.status = response.status;
+    this.headers = new Headers(response.headers);
+    this.body = body;
+  }
+};
+function bodyRequestId(body) {
+  if (typeof body === "object" && body !== null && "requestId" in body) {
+    return typeof body.requestId === "string" ? body.requestId : void 0;
+  }
+  return void 0;
+}
+function createTransport(options) {
+  const url = new URL(options.baseUrl);
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new TypeError(
+      "baseUrl must be an absolute HTTP(S) API root without credentials, query or fragment"
+    );
+  }
+  const headers = new Headers(options.headers);
+  headers.set("accept", "application/json");
+  if (options.apiKey !== void 0) headers.set("x-api-key", options.apiKey);
+  return createClient({
+    baseUrl: url.href.replace(/\/+$/, ""),
+    headers,
+    fetch: options.fetch,
+    credentials: options.credentials
+  });
+}
+async function result(pending, allowEmpty = false) {
+  const { response, data, error } = await pending;
+  if (!response.ok) throw new ApiError(response, error);
+  if (data === void 0 || data === "") {
+    if (allowEmpty) return void 0;
+    throw new ResponseParseError(
+      response,
+      "",
+      new SyntaxError("Expected a JSON response body")
+    );
+  }
+  try {
+    return JSON.parse(data);
+  } catch (cause) {
+    throw new ResponseParseError(response, data, cause);
+  }
+}
+function textOptions(options) {
+  return { ...options, parseAs: "text" };
+}
+
+export {
+  ApiError,
+  ResponseParseError,
+  createTransport,
+  result,
+  textOptions
+};

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { R as RequestOptions, y as CatalogGateway, z as CreateLeaseInput, L as Lease, D as ReportLeaseInput, v as ProxyClientOptions } from './transport-CWjoRf8k.js';
+export { w as ApiError, x as ResponseParseError } from './transport-CWjoRf8k.js';
+
+interface ProxyClient {
+    gateways: {
+        list(options?: RequestOptions): Promise<CatalogGateway[]>;
+    };
+    leases: {
+        create(input: CreateLeaseInput, options?: RequestOptions): Promise<Lease>;
+        get(id: string, options?: RequestOptions): Promise<Lease>;
+        renew(id: string, options?: RequestOptions): Promise<Lease>;
+        release(id: string, options?: RequestOptions): Promise<void>;
+        report(id: string, input: ReportLeaseInput, options?: RequestOptions): Promise<void>;
+    };
+}
+/** Application control-plane API. The key's permissions are enforced by the server. */
+declare function createProxyClient(options: ProxyClientOptions): ProxyClient;
+
+export { CatalogGateway, CreateLeaseInput, Lease, ProxyClientOptions, ReportLeaseInput, RequestOptions, createProxyClient };
+export type { ProxyClient };

package/dist/index.js

@@ -0,0 +1,49 @@
+import {
+  ApiError,
+  ResponseParseError,
+  createTransport,
+  result,
+  textOptions
+} from "./chunk-6QCKYRE3.js";
+
+// src/index.ts
+function createProxyClient(options) {
+  const http = createTransport(options);
+  return {
+    gateways: {
+      list: (options2) => result(http.GET("/gateways", { ...textOptions(options2) }))
+    },
+    leases: {
+      create: (body, options2) => result(http.POST("/leases", { ...textOptions(options2), body })),
+      get: (id, options2) => result(
+        http.GET("/leases/{id}", { ...textOptions(options2), params: { path: { id } } })
+      ),
+      renew: (id, options2) => result(
+        http.PATCH("/leases/{id}", {
+          ...textOptions(options2),
+          params: { path: { id } }
+        })
+      ),
+      release: (id, options2) => result(
+        http.DELETE("/leases/{id}", {
+          ...textOptions(options2),
+          params: { path: { id } }
+        }),
+        true
+      ),
+      report: (id, body, options2) => result(
+        http.POST("/leases/{id}/report", {
+          ...textOptions(options2),
+          params: { path: { id } },
+          body
+        }),
+        true
+      )
+    }
+  };
+}
+export {
+  ApiError,
+  ResponseParseError,
+  createProxyClient
+};