@distilled.cloud/stackit 0.0.0-placeholder → 1.0.0-rc.13

package/package.json

@@ -1,15 +1,86 @@
 {
   "name": "@distilled.cloud/stackit",
-  "version": "0.0.0-placeholder",
-  "description": "Placeholder package for initial npm registration.",
-  "license": "Apache-2.0",
+  "version": "1.0.0-rc.13",
   "repository": {
     "type": "git",
     "url": "https://github.com/alchemy-run/distilled",
     "directory": "packages/stackit"
   },
-  "publishConfig": {
-    "access": "public",
-    "tag": "placeholder"
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "module": "src/index.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "worker": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./Credentials": {
+      "types": "./lib/credentials.d.ts",
+      "bun": "./src/credentials.ts",
+      "worker": "./src/credentials.ts",
+      "default": "./lib/credentials.js"
+    },
+    "./Errors": {
+      "types": "./lib/errors.d.ts",
+      "bun": "./src/errors.ts",
+      "worker": "./src/errors.ts",
+      "default": "./lib/errors.js"
+    },
+    "./Pagination": {
+      "types": "./lib/pagination.d.ts",
+      "bun": "./src/pagination.ts",
+      "worker": "./src/pagination.ts",
+      "default": "./lib/pagination.js"
+    },
+    "./Protocol": {
+      "types": "./lib/protocol.d.ts",
+      "bun": "./src/protocol.ts",
+      "worker": "./src/protocol.ts",
+      "default": "./lib/protocol.js"
+    },
+    "./Retry": {
+      "types": "./lib/retry.d.ts",
+      "bun": "./src/retry.ts",
+      "worker": "./src/retry.ts",
+      "default": "./lib/retry.js"
+    },
+    "./Traits": {
+      "types": "./lib/traits.d.ts",
+      "bun": "./src/traits.ts",
+      "worker": "./src/traits.ts",
+      "default": "./lib/traits.js"
+    },
+    "./*": {
+      "types": "./lib/services/*.d.ts",
+      "bun": "./src/services/*.ts",
+      "worker": "./src/services/*.ts",
+      "default": "./lib/services/*.js"
+    }
+  },
+  "dependencies": {
+    "@distilled.cloud/core": "1.0.0-rc.13"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "@types/node": "26.2.0",
+    "@effect/platform-bun": "^4.0.0"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "convert": "bun scripts/convert.ts",
+    "generate": "bun scripts/generate.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "specs:fetch": "git submodule update --force --init --depth=1 specs/spec-mirror-stackit",
+    "specs:update": "git submodule update --remote --force --depth=1 specs/spec-mirror-stackit"
   }
-}
+}

package/src/credentials.ts

@@ -0,0 +1,90 @@
+/**
+ * STACKIT credentials — hand-written.
+ *
+ * The `Credentials` service resolves `{ token, region }` per request; the
+ * protocol layer formats the `Authorization: Bearer <token>` header from it
+ * and rewrites each operation's spec `servers` URL for the region. The token
+ * is a STACKIT service-account access token — the same value the official
+ * Go SDK, CLI and Terraform provider read from
+ * `STACKIT_SERVICE_ACCOUNT_TOKEN`. Key-file exchange
+ * (`STACKIT_SERVICE_ACCOUNT_KEY_PATH`) is not modelled: mint the token
+ * outside the SDK.
+ *
+ * Each STACKIT product has its own host (`iaas.api.eu01.stackit.cloud`,
+ * `ske.api.eu01.stackit.cloud`, …). The per-operation host is baked into
+ * the generated `T.Http` trait from the OpenAPI `servers` entry; `region`
+ * (default `eu01`) is substituted at request time. An explicit `apiBaseUrl`
+ * overrides that host for every call — a proxy, not a per-product map.
+ */
+import * as EffectConfig from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { ConfigError } from "@distilled.cloud/core/errors";
+
+/** STACKIT's primary public region (Schwarz IT / Germany). */
+export const DEFAULT_REGION = "eu01";
+
+export interface Config {
+  readonly token: Redacted.Redacted<string>;
+  /**
+   * Region inserted into product hosts (`eu01` →
+   * `https://iaas.api.eu01.stackit.cloud`). `"global"` leaves the spec URL
+   * unchanged.
+   */
+  readonly region: string;
+  /** When set, every operation uses this host instead of the spec's. */
+  readonly apiBaseUrl?: string;
+}
+
+export class Credentials extends Context.Service<
+  Credentials,
+  Effect.Effect<Config>
+>()("StackitCredentials") {}
+
+const envConfig = EffectConfig.all({
+  // `STACKIT_SERVICE_ACCOUNT_TOKEN` / `STACKIT_REGION` are what the
+  // official Go SDK, CLI and Terraform provider read.
+  token: EffectConfig.String("STACKIT_SERVICE_ACCOUNT_TOKEN"),
+  region: EffectConfig.String("STACKIT_REGION").pipe(
+    EffectConfig.withDefault(DEFAULT_REGION),
+  ),
+  apiBaseUrl: EffectConfig.String("STACKIT_API_BASE_URL").pipe(
+    EffectConfig.option,
+  ),
+});
+
+export const CredentialsFromEnv = Layer.succeed(
+  Credentials,
+  envConfig.pipe(
+    Effect.mapError(
+      () =>
+        new ConfigError({
+          message:
+            "STACKIT_SERVICE_ACCOUNT_TOKEN environment variable is required",
+        }),
+    ),
+    Effect.map(({ token, region, apiBaseUrl }) => ({
+      token: Redacted.make(token),
+      region,
+      apiBaseUrl: apiBaseUrl._tag === "Some" ? apiBaseUrl.value : undefined,
+    })),
+    Effect.orDie,
+  ),
+);
+
+/** Convenience layer from a plain token + optional region / base URL. */
+export const credentials = (config: {
+  readonly token: string;
+  readonly region?: string;
+  readonly apiBaseUrl?: string;
+}): Layer.Layer<Credentials> =>
+  Layer.succeed(
+    Credentials,
+    Effect.succeed({
+      token: Redacted.make(config.token),
+      region: config.region ?? DEFAULT_REGION,
+      apiBaseUrl: config.apiBaseUrl,
+    }),
+  );

package/src/errors.ts

@@ -0,0 +1,50 @@
+/**
+ * STACKIT-specific error types.
+ *
+ * Re-exports the common HTTP errors from core and adds the unknown-error
+ * and parse-error wrappers. STACKIT failures carry `{ message, error? }`
+ * (the `ErrorMessage` schema in most of the product specs); the protocol
+ * reads `message` for the human half and `error` as the machine-readable
+ * code on {@link UnknownStackitError}.
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  Locked,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+export type { DefaultErrors } from "@distilled.cloud/core/errors";
+
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+/** Unknown STACKIT error — returned when nothing else matches the failure. */
+export class UnknownStackitError extends Schema.TaggedError<UnknownStackitError>()(
+  "UnknownStackitError",
+  {
+    code: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+    body: Schema.Unknown,
+  },
+).pipe(Category.withServerError) {}
+
+/** Schema parse error wrapper. */
+export class StackitParseError extends Schema.TaggedError<StackitParseError>()(
+  "StackitParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @distilled.cloud/stackit — STACKIT Cloud API SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models
+ * in `.generated-specs` (written by `scripts/convert.ts` from the OpenAPI
+ * documents mirrored at `specs/spec-mirror-stackit/specs/`). Everything else
+ * in this folder is hand-written.
+ *
+ * One module per STACKIT product (IaaS, SKE, DNS, Postgres Flex, …), using
+ * that product's latest published OpenAPI version. Auth is a service-account
+ * bearer token (`STACKIT_SERVICE_ACCOUNT_TOKEN`); each product's host is
+ * rewritten for `STACKIT_REGION` (default `eu01`).
+ *
+ * @example
+ * ```ts
+ * import * as Stackit from "@distilled.cloud/stackit";
+ *
+ * const { zones } = yield* Stackit.dns.listZones({
+ *   projectId: "...",
+ * });
+ * ```
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as T from "./traits.ts";
+export {
+  StackitProtocol,
+  applyRegion,
+  type StackitOpError,
+  type StackitOpContext,
+} from "./protocol.ts";
+export { paginateByTotalPages } from "./pagination.ts";
+export * as Retry from "./retry.ts";
+export * from "./services/index.ts";

package/src/pagination.ts

@@ -0,0 +1,73 @@
+/**
+ * STACKIT pagination — hand-written.
+ *
+ * Several STACKIT list operations page by NUMBER: `?page=N&pageSize=M` in,
+ * and a response carrying the collection beside `totalPages` (DNS zones /
+ * record sets, and the same envelope on other products). Core's
+ * `paginatePageNumber` treats `outputToken` as the NEXT page number, so
+ * pointing it at `totalPages` would jump to the last page; this strategy
+ * advances by one until `page >= totalPages`.
+ */
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import {
+  getPath,
+  type PaginationStrategy,
+} from "@distilled.cloud/core/pagination";
+
+export type {
+  PaginatedTrait,
+  PaginationStrategy,
+} from "@distilled.cloud/core/pagination";
+
+/**
+ * Stream of pages using STACKIT's `page` / `totalPages` envelope: request
+ * `page`, `page+1`, … while `page < totalPages` and the collection is
+ * non-empty.
+ */
+export const paginateByTotalPages: PaginationStrategy = (
+  operation,
+  input,
+  pagination,
+) => {
+  const inputToken = pagination.inputToken;
+  const totalPagesPath = pagination.outputToken;
+  const itemsPath = pagination.items;
+  if (!inputToken || !totalPagesPath) {
+    return Stream.die(
+      new Error(
+        "Total-pages pagination requires inputToken and outputToken (totalPages)",
+      ),
+    );
+  }
+
+  type State = { page: number; done: boolean };
+  const startPage =
+    typeof input[inputToken] === "number" ? (input[inputToken] as number) : 1;
+
+  return Stream.unfold({ page: startPage, done: false } as State, (state) =>
+    Effect.gen(function* () {
+      if (state.done) return undefined;
+
+      const requestPayload = {
+        ...input,
+        [inputToken]: state.page,
+      } as typeof input;
+      const response = yield* operation(requestPayload);
+
+      const totalPages = getPath(response, totalPagesPath);
+      const items = itemsPath
+        ? (getPath(response, itemsPath) as readonly unknown[] | undefined)
+        : undefined;
+      const exhausted =
+        typeof totalPages !== "number" ||
+        state.page >= totalPages ||
+        (items !== undefined && items.length === 0);
+
+      return [
+        response,
+        { page: state.page + 1, done: exhausted } satisfies State,
+      ] as const;
+    }),
+  );
+};

package/src/protocol.ts

@@ -0,0 +1,243 @@
+/**
+ * StackitProtocol — the shared bearer-REST protocol instantiated for STACKIT.
+ *
+ * STACKIT speaks plain JSON with no success envelope. FAILURES are
+ * `{ "message": "...", "error": "..." }` (the `ErrorMessage` schema most
+ * product specs share). Each product has its own host, baked into the
+ * generated operation's `T.Http({ baseUrl })` from the OpenAPI `servers`
+ * entry; this protocol reads that URL and rewrites it for the configured
+ * region (`eu01` by default).
+ *
+ * Auth is `Authorization: Bearer <token>`. The API version is a PATH
+ * segment (`/v1`, `/v2`, …), so the generated operations carry versioned
+ * routes against a version-less host.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type * as AST from "effect/SchemaAST";
+import type * as HttpClient from "effect/http/HttpClient";
+import type * as HttpClientError from "effect/http/HttpClientError";
+import type * as HttpClientRequest from "effect/http/HttpClientRequest";
+import type * as HttpClientResponse from "effect/http/HttpClientResponse";
+import * as API from "@distilled.cloud/core/api";
+import {
+  HTTP_STATUS_MAP,
+  InternalServerError,
+  type ConfigError,
+} from "@distilled.cloud/core/errors";
+import {
+  buildRequest,
+  getAnn,
+  mapKeys,
+  matchTypedError,
+} from "@distilled.cloud/core/protocol-http";
+import {
+  unwrapRedactedDeep,
+  wrapSensitive,
+  type RestErrorEnvelope,
+} from "@distilled.cloud/core/protocol-rest";
+import { validateResponse } from "@distilled.cloud/core/response-validation";
+import { parseRetryAfterForStatus } from "@distilled.cloud/core/retry-after";
+import { httpSymbol } from "@distilled.cloud/core/trait";
+import { Credentials, type Config } from "./credentials.ts";
+import { StackitParseError, UnknownStackitError } from "./errors.ts";
+import type { DefaultErrors } from "./errors.ts";
+import type { StackitHttpTrait } from "./traits.ts";
+
+/**
+ * Error channel shared by every generated STACKIT operation. Generated
+ * service files annotate operations with `API.OperationMethod<I, O,
+ * StackitOpError, StackitOpContext>` explicitly so the compiler never infers
+ * these back out of the schema generics.
+ */
+export type StackitOpError =
+  | DefaultErrors
+  | UnknownStackitError
+  | StackitParseError
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated STACKIT operation. */
+export type StackitOpContext = Credentials | HttpClient.HttpClient;
+
+/**
+ * Rewrite a spec `servers` URL for the configured region.
+ *
+ *   • `{region}` still in the template (IaaS v1:
+ *     `https://iaas.api.{region}stackit.cloud`, default `eu01.`) is
+ *     substituted. A glued `{region}stackit` means the spec's default
+ *     includes the trailing dot.
+ *   • `https://<svc>.api.stackit.cloud` becomes
+ *     `https://<svc>.api.<region>.stackit.cloud`.
+ *   • `region === "global"` leaves the URL alone (after dropping any
+ *     leftover `{region}`).
+ */
+export const applyRegion = (specUrl: string, region: string): string => {
+  if (specUrl.includes("{region}")) {
+    if (region === "global") return specUrl.replaceAll("{region}", "");
+    const glued = specUrl.includes("{region}stackit");
+    const value = glued && !region.endsWith(".") ? `${region}.` : region;
+    return specUrl.replaceAll("{region}", value);
+  }
+  if (region === "global") return specUrl;
+  return specUrl.replace(
+    /^(https:\/\/[a-z0-9-]+)\.api\.stackit\.cloud(?=[:/?]|$)/i,
+    `$1.api.${region}.stackit.cloud`,
+  );
+};
+
+const errorEnvelope = (body: unknown): RestErrorEnvelope | undefined => {
+  if (body === null || typeof body !== "object") return undefined;
+  const b = body as Record<string, unknown>;
+  const message = typeof b.message === "string" ? b.message : undefined;
+  const code =
+    typeof b.error === "string"
+      ? b.error
+      : typeof b.code === "string" || typeof b.code === "number"
+        ? b.code
+        : undefined;
+  if (message === undefined && code === undefined) return undefined;
+  return { code, message };
+};
+
+const fail = (e: unknown): Effect.Effect<never> =>
+  Effect.fail(e) as Effect.Effect<never>;
+
+const baseUrlFor = (creds: Config, inputAst: AST.AST): string => {
+  if (creds.apiBaseUrl !== undefined && creds.apiBaseUrl !== "") {
+    return creds.apiBaseUrl;
+  }
+  const http = getAnn(inputAst, httpSymbol) as StackitHttpTrait | undefined;
+  const specUrl = http?.baseUrl;
+  if (typeof specUrl !== "string" || specUrl === "") {
+    throw new Error(
+      "STACKIT operation is missing T.Http({ baseUrl }) — regenerate from convert",
+    );
+  }
+  return applyRegion(specUrl, creds.region);
+};
+
+export const StackitProtocol: Layer.Layer<API.Protocol> = Layer.succeed(
+  API.Protocol,
+  API.Protocol.of({
+    encode: ({
+      input,
+      inputAst,
+    }: {
+      readonly input: unknown;
+      readonly inputAst: AST.AST;
+    }) =>
+      Effect.gen(function* () {
+        const resolve = yield* Credentials;
+        const creds = yield* resolve;
+        return buildRequest({
+          input: unwrapRedactedDeep(input),
+          inputAst,
+          baseUrl: baseUrlFor(creds, inputAst),
+          headers: {
+            Authorization: `Bearer ${Redacted.value(creds.token)}`,
+          },
+        });
+      }) as Effect.Effect<HttpClientRequest.HttpClientRequest>,
+    decode: ({
+      response,
+      outputAst,
+      errors: errorClasses,
+    }: {
+      readonly response: HttpClientResponse.HttpClientResponse;
+      readonly outputAst: AST.AST;
+      readonly errors: ReadonlyArray<unknown>;
+    }) =>
+      Effect.gen(function* () {
+        const text = (yield* response.text.pipe(Effect.orDie)) ?? "";
+        if (process.env.DISTILLED_DEBUG_HTTP) {
+          console.error(
+            `[distilled] <- ${response.status} ${text.slice(0, 400)}`,
+          );
+        }
+        let json: unknown;
+        let nonJson = false;
+        if (text.trim().length > 0) {
+          try {
+            json = JSON.parse(text);
+          } catch {
+            nonJson = true;
+          }
+        }
+        const status = response.status;
+        const headers = response.headers as Record<string, string | undefined>;
+
+        if (status >= 400) {
+          const env = (nonJson ? undefined : errorEnvelope(json)) ?? {};
+          const message =
+            env.message ??
+            (nonJson && text.trim() ? text.trim() : `HTTP ${status}`);
+
+          const typed = matchTypedError(
+            errorClasses,
+            status,
+            [
+              {
+                code: typeof env.code === "number" ? env.code : undefined,
+                message,
+              },
+            ],
+            { body: nonJson ? text : json, headers },
+          );
+          if (typed !== undefined) return yield* fail(typed);
+
+          const StatusErrorClass = (
+            HTTP_STATUS_MAP as Record<
+              number,
+              | (new (args: {
+                  message: string;
+                  retryAfter?: unknown;
+                }) => unknown)
+              | undefined
+            >
+          )[status];
+          if (StatusErrorClass) {
+            return yield* fail(
+              new StatusErrorClass({
+                message,
+                retryAfter: parseRetryAfterForStatus(status, headers),
+              }),
+            );
+          }
+
+          if (status >= 500) {
+            return yield* fail(
+              new InternalServerError({
+                message,
+                retryAfter: parseRetryAfterForStatus(status, headers),
+              }),
+            );
+          }
+
+          return yield* fail(
+            new UnknownStackitError({
+              code:
+                typeof env.code === "string"
+                  ? env.code
+                  : env.code !== undefined
+                    ? String(env.code)
+                    : undefined,
+              message,
+              body: nonJson ? text : json,
+            }),
+          );
+        }
+
+        // Strict mode checks the mapped body against the output schema.
+        const body: unknown = nonJson ? text : (json ?? {});
+        const mapped = yield* validateResponse(
+          outputAst,
+          mapKeys(outputAst, body, "decode"),
+          (cause) =>
+            new StackitParseError({ body: nonJson ? text : json, cause }),
+        ).pipe(Effect.catch(fail));
+        return wrapSensitive(outputAst, mapped);
+      }),
+  }),
+);

package/src/response-validation.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { runValidationModes } from "@distilled.cloud/core/testing";
+import * as Effect from "effect/Effect";
+import { credentials } from "./credentials.ts";
+import { StackitParseError } from "./errors.ts";
+import * as Retry from "./retry.ts";
+import { listKeyPairs } from "./services/iaas.ts";
+import type { StackitOpError } from "./protocol.ts";
+
+// listKeyPairs declares `{ items: Keypair[] }`.
+const run = (body: string) =>
+  runValidationModes(
+    listKeyPairs({}).pipe(
+      Retry.none,
+      Effect.provide(credentials({ token: "test" })),
+    ),
+    { body },
+  );
+
+describe("STACKIT response validation", () => {
+  test("a matching body succeeds unchanged in both modes", async () => {
+    const body = { items: [{ name: "key-1", publicKey: "ssh-ed25519 AAAA" }] };
+    const { lenient, strict } = await run(JSON.stringify(body));
+    expect(lenient).toMatchObject({ _tag: "Success", success: body });
+    expect(strict).toMatchObject({ _tag: "Success", success: body });
+  });
+
+  test("a body missing required members: lenient returns it, strict fails", async () => {
+    const { lenient, strict } = await run("{}");
+    expect(lenient).toMatchObject({ _tag: "Success", success: {} });
+    expect(strict._tag).toBe("Failure");
+    expect((strict as any).failure).toBeInstanceOf(StackitParseError);
+  });
+
+  test("a non-JSON body: lenient returns the text, strict fails", async () => {
+    const { lenient, strict } = await run("not json");
+    expect(lenient).toMatchObject({ _tag: "Success", success: "not json" });
+    expect((strict as any).failure).toBeInstanceOf(StackitParseError);
+  });
+});
+
+// StackitParseError is part of every operation's declared error type.
+export const parseErrorIsDeclared: [StackitParseError] extends [StackitOpError]
+  ? true
+  : false = true;

package/src/retry.ts

@@ -0,0 +1,53 @@
+/**
+ * STACKIT retry configuration.
+ *
+ * Defines the per-SDK `Retry` Context.Service tag that generated operations
+ * wire into `API.make`. Callers can install a blanket retry policy at the
+ * layer level and have every STACKIT API call below it pick it up:
+ *
+ * @example
+ * ```ts
+ * import * as Stackit from "@distilled.cloud/stackit";
+ *
+ * myEffect.pipe(Stackit.Retry.transient);
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+  type Policy,
+  throttlingFactory,
+  transientFactory,
+} from "@distilled.cloud/core/retry";
+
+export {
+  type Options,
+  type Factory,
+  type Policy,
+  makeDefault,
+  jittered,
+  capped,
+  throttlingOptions,
+  transientOptions,
+  throttlingFactory,
+  transientFactory,
+} from "@distilled.cloud/core/retry";
+
+/** Context tag for configuring retry behavior of STACKIT API calls. */
+export class Retry extends Context.Service<Retry, Policy>()("StackitRetry") {}
+
+/** Provides a custom retry policy to every STACKIT API call below it. */
+export const policy = (optionsOrFactory: Policy) =>
+  Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+
+/** Disables all automatic retries. */
+export const none = Effect.provide(
+  Layer.succeed(Retry, { while: () => false }),
+);
+
+/** Apply the throttling retry policy (retries throttling errors indefinitely). */
+export const throttling = policy(throttlingFactory);
+
+/** Apply the transient retry policy (retries all transient errors indefinitely). */
+export const transient = policy(transientFactory);