@distilled.cloud/fly-io 1.0.0-rc.1 → 1.0.0-rc.11

package/src/credentials.ts

@@ -1,10 +1,17 @@
 /**
  * Fly.io credentials — hand-written.
  *
- * API-compatible port of the distilled v0 fly-io credentials module: the
- * `Credentials` service holds an *effect* that resolves the current
+ * 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: Bearer <apiKey>` header.
+ * 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";
@@ -13,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>;
@@ -26,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(
@@ -35,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

@@ -29,12 +29,13 @@ import type { DefaultErrors as CoreDefaultErrors } from "@distilled.cloud/core/e
 
 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 a failure matches no status-mapped
  * error class. Carries the raw body for later cataloging.
  */
-export class UnknownFlyIoError extends Schema.TaggedErrorClass<UnknownFlyIoError>()(
+export class UnknownFlyIoError extends Schema.TaggedError<UnknownFlyIoError>()(
   "UnknownFlyIoError",
   {
     code: Schema.optional(Schema.String),
@@ -44,7 +45,7 @@ export class UnknownFlyIoError extends Schema.TaggedErrorClass<UnknownFlyIoError
 ).pipe(Category.withServerError) {}
 
 /** Schema parse error wrapper. */
-export class FlyIoParseError extends Schema.TaggedErrorClass<FlyIoParseError>()(
+export class FlyIoParseError extends Schema.TaggedError<FlyIoParseError>()(
   "FlyIoParseError",
   {
     body: Schema.Unknown,
@@ -52,6 +53,44 @@ export class FlyIoParseError extends Schema.TaggedErrorClass<FlyIoParseError>()(
   },
 ).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.

package/src/index.ts

@@ -4,14 +4,45 @@
  * `./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 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 * 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 * as Services from "./services/index.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";