@distilled.cloud/fly-io 0.30.3 → 1.0.0-rc.10

package/src/credentials.ts

@@ -1,3 +1,18 @@
+/**
+ * Fly.io credentials — hand-written.
+ *
+ * The `Credentials` service holds an *effect* that resolves the current
+ * credentials on every request. The protocol layer resolves it per request
+ * and formats the `Authorization` header.
+ *
+ * Alchemy and `flyctl` read `FLY_API_TOKEN`. `FLY_IO_API_KEY` is kept as a
+ * fallback for older distilled consumers. Optional `FLY_API_HOSTNAME`
+ * overrides the Machines API host (default `https://api.machines.dev`).
+ *
+ * Managed REST (MPG), GraphQL add-ons (Tigris, Redis), and Sprites all
+ * reuse this token. Sprites never reads a separate env var: the protocol
+ * mints a Sprites bearer from `FLY_API_TOKEN` (see `SpritesProtocol`).
+ */
 import { ConfigError } from "@distilled.cloud/core/errors";
 import * as EffectConfig from "effect/Config";
 import * as Context from "effect/Context";
@@ -5,7 +20,33 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
 
-export const DEFAULT_API_BASE_URL = "https://api.machines.dev/v1";
+/**
+ * Machines API host. The generated Machines routes carry the `/v1` prefix
+ * (`/v1/apps/{app_name}/machines`), as the upstream OpenAPI spells them, so
+ * the base URL must not.
+ */
+export const DEFAULT_API_BASE_URL = "https://api.machines.dev";
+
+/** UI-EX REST + GraphQL host (MPG, Tigris, Redis). Not overridable via an invented env var. */
+export const DEFAULT_FLY_API_BASE_URL = "https://api.fly.io";
+
+/** Sprites REST root. Auth is a bearer minted from `FLY_API_TOKEN` — never `SPRITES_TOKEN`. */
+export const DEFAULT_SPRITES_API_BASE_URL = "https://api.sprites.dev/v1";
+
+/**
+ * Normalize a Fly API hostname into the Machines API base URL.
+ *
+ * - unset / empty → `https://api.machines.dev`
+ * - trailing slashes stripped
+ * - a trailing `/v1` is dropped: `flyctl` and older consumers set
+ *   `FLY_API_HOSTNAME` to the `/v1` root, and the routes already carry it
+ */
+export const normalizeApiBaseUrl = (hostname?: string): string => {
+  if (hostname === undefined) return DEFAULT_API_BASE_URL;
+  const trimmed = hostname.trim().replace(/\/+$/, "");
+  if (trimmed.length === 0) return DEFAULT_API_BASE_URL;
+  return trimmed.endsWith("/v1") ? trimmed.slice(0, -3) : trimmed;
+};
 
 export interface Config {
   readonly apiKey: Redacted.Redacted<string>;
@@ -18,7 +59,12 @@ export class Credentials extends Context.Service<
 >()("Fly-ioCredentials") {}
 
 const envConfig = EffectConfig.all({
-  apiKey: EffectConfig.string("FLY_IO_API_KEY"),
+  apiKey: EffectConfig.String("FLY_API_TOKEN").pipe(
+    EffectConfig.orElse(() => EffectConfig.String("FLY_IO_API_KEY")),
+  ),
+  apiBaseUrl: EffectConfig.String("FLY_API_HOSTNAME").pipe(
+    EffectConfig.withDefault(""),
+  ),
 });
 
 export const CredentialsFromEnv = Layer.succeed(
@@ -27,13 +73,27 @@ export const CredentialsFromEnv = Layer.succeed(
     Effect.mapError(
       () =>
         new ConfigError({
-          message: "FLY_IO_API_KEY environment variable is required",
+          message:
+            "FLY_API_TOKEN (or FLY_IO_API_KEY) environment variable is required",
         }),
     ),
-    Effect.map(({ apiKey }) => ({
+    Effect.map(({ apiKey, apiBaseUrl }) => ({
       apiKey: Redacted.make(apiKey),
-      apiBaseUrl: DEFAULT_API_BASE_URL,
+      apiBaseUrl: normalizeApiBaseUrl(apiBaseUrl || undefined),
     })),
     Effect.orDie,
   ),
 );
+
+/** Convenience layer from a plain API token + optional base URL. */
+export const credentials = (config: {
+  readonly apiKey: string;
+  readonly apiBaseUrl?: string;
+}): Layer.Layer<Credentials> =>
+  Layer.succeed(
+    Credentials,
+    Effect.succeed({
+      apiKey: Redacted.make(config.apiKey),
+      apiBaseUrl: normalizeApiBaseUrl(config.apiBaseUrl),
+    }),
+  );

package/src/errors.ts

@@ -1,8 +1,11 @@
 /**
- * Fly-io-specific error types.
+ * Fly.io-specific error types.
  *
- * Re-exports common HTTP errors from sdk-core and adds Fly-io-specific
- * error matching and API error types.
+ * Re-exports common HTTP errors from sdk-core and adds the Fly.io-specific
+ * fallback/parse error types. Fly.io's error model is a pure HTTP-status
+ * map: the API answers failures with `{ "error": "..." }` and the protocol
+ * maps the status onto the shared core classes (BadRequest / Forbidden /
+ * NotFound / Conflict / UnprocessableEntity / ...).
  */
 export {
   BadGateway,
@@ -22,13 +25,17 @@ export {
   DEFAULT_ERRORS,
   API_ERRORS,
 } from "@distilled.cloud/core/errors";
-export type { DefaultErrors } from "@distilled.cloud/core/errors";
+import type { DefaultErrors as CoreDefaultErrors } from "@distilled.cloud/core/errors";
 
 import * as Schema from "effect/Schema";
 import * as Category from "@distilled.cloud/core/category";
+import { applyErrorMatchers } from "@distilled.cloud/core/trait";
 
-// Unknown Fly-io error - returned when an error code is not recognized
-export class UnknownFlyIoError extends Schema.TaggedErrorClass<UnknownFlyIoError>()(
+/**
+ * Unknown Fly.io error — returned when a failure matches no status-mapped
+ * error class. Carries the raw body for later cataloging.
+ */
+export class UnknownFlyIoError extends Schema.TaggedError<UnknownFlyIoError>()(
   "UnknownFlyIoError",
   {
     code: Schema.optional(Schema.String),
@@ -37,11 +44,61 @@ export class UnknownFlyIoError extends Schema.TaggedErrorClass<UnknownFlyIoError
   },
 ).pipe(Category.withServerError) {}
 
-// Schema parse error wrapper
-export class FlyIoParseError extends Schema.TaggedErrorClass<FlyIoParseError>()(
+/** Schema parse error wrapper. */
+export class FlyIoParseError extends Schema.TaggedError<FlyIoParseError>()(
   "FlyIoParseError",
   {
     body: Schema.Unknown,
     cause: Schema.Unknown,
   },
 ).pipe(Category.withParseError) {}
+
+/**
+ * Sprites is not enabled for the Fly organization that owns `FLY_API_TOKEN`.
+ *
+ * Returned by `POST /v1/organizations/{org}/tokens` as HTTP 401 with a
+ * message matching `sprites not enabled`. Sprite CRUD never sees a
+ * `SPRITES_TOKEN` — this is the mint-time entitlement signal.
+ */
+export class SpritesNotEnabled extends Schema.TaggedError<SpritesNotEnabled>()(
+  "SpritesNotEnabled",
+  {
+    code: Schema.optional(Schema.Int),
+    message: Schema.optional(Schema.String),
+  },
+).pipe(Category.withAuthError) {}
+applyErrorMatchers(SpritesNotEnabled, [
+  { status: 401, message: { matches: "[Ss]prites not enabled" } },
+]);
+
+/**
+ * The Fly token cannot record add-on provider ToS agreement
+ * (`createExtensionTosAgreement`). GraphQL returns this as a 200
+ * with `Not authorized to access this createextensiontosagreement`.
+ */
+export class CreateExtensionTosAgreementNotAuthorized extends Schema.TaggedError<CreateExtensionTosAgreementNotAuthorized>()(
+  "CreateExtensionTosAgreementNotAuthorized",
+  {
+    code: Schema.optional(Schema.Int),
+    message: Schema.optional(Schema.String),
+  },
+).pipe(Category.withAuthError) {}
+applyErrorMatchers(CreateExtensionTosAgreementNotAuthorized, [
+  {
+    message: {
+      matches: "[Nn]ot authorized to access this createextensiontosagreement",
+    },
+  },
+]);
+
+/**
+ * Errors any Fly.io operation may surface in addition to the status-mapped
+ * per-operation errors.
+ */
+export type ClientErrors = UnknownFlyIoError | FlyIoParseError;
+
+/**
+ * Default Fly.io operation errors: the shared HTTP status errors from core
+ * plus the client-level fallback/decode errors.
+ */
+export type DefaultErrors = CoreDefaultErrors | ClientErrors;

package/src/index.ts

@@ -1,16 +1,48 @@
 /**
- * Fly-io SDK for Effect
+ * @distilled.cloud/fly-io — Fly.io SDK for Effect.
  *
- * @example
+ * `./services` is generated by `scripts/generate.ts` from the Smithy model
+ * written by `scripts/convert.ts` (OpenAPI → Smithy via the shared core
+ * converter). Everything else in this folder is hand-written.
+ *
+ * The generated barrel is re-exported at the package root, same as every
+ * other distilled SDK's service modules:
+ *
+ * @example Package namespace
  * ```ts
- * import * as Fly-io from "@distilled.cloud/fly-io";
+ * import * as Fly from "@distilled.cloud/fly-io";
+ *
+ * yield* Fly.machines.listApps({ org_slug });
+ * yield* Fly.mpg.createCluster({
+ *   name, region, org_slug, plan, pg_major_version: "16", storage_in_gb: 10,
+ * });
+ * yield* Fly.addons.createAddOn({
+ *   input: { type: "tigris", name, options: { website: { domain_name: "" } } },
+ * });
+ * yield* Fly.sprites.createSprite({ name, labels: ["alchemy"] });
+ * ```
+ *
+ * @example Per-service path
+ * ```ts
+ * import * as Machines from "@distilled.cloud/fly-io/machines";
+ *
+ * yield* Machines.listApps({ org_slug });
  * ```
  */
 export * from "./credentials.ts";
-export * as Category from "./category.ts";
+export * from "./errors.ts";
 export * as T from "./traits.ts";
+export {
+  FlyIoProtocol,
+  FlyApiProtocol,
+  FlyGraphqlProtocol,
+  SpritesProtocol,
+  MachineIdentity,
+  type FlyIoOpError,
+  type FlyIoOpContext,
+  type SpritesOpError,
+  type SpritesOpContext,
+} from "./protocol.ts";
 export * as Retry from "./retry.ts";
-export { API } from "./client.ts";
-export * from "./errors.ts";
-export * from "./operations/index.ts";
-export { SensitiveString, SensitiveNullableString } from "./sensitive.ts";
+export * as Pagination from "./pagination.ts";
+export * from "./services/index.ts";

package/src/pagination.ts

@@ -0,0 +1,12 @@
+/**
+ * Fly.io pagination — cursor (Sprites list) and Relay (GraphQL add-ons).
+ */
+export {
+  paginateCursor,
+  paginateRelay,
+  extractItems,
+  getItems,
+  getPath,
+  type PaginatedTrait,
+  type PaginationStrategy,
+} from "@distilled.cloud/core/pagination";