@distilled.cloud/fly-io 1.0.0-rc.4 → 1.0.0-rc.6

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 root (default `https://api.machines.dev/v1`).
+ *
+ * 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";
@@ -15,6 +22,26 @@ import * as Redacted from "effect/Redacted";
 
 export const DEFAULT_API_BASE_URL = "https://api.machines.dev/v1";
 
+/** 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 root.
+ *
+ * - unset / empty → `https://api.machines.dev/v1`
+ * - already ends with `/v1` → used as-is (trailing slashes stripped)
+ * - otherwise `/v1` is appended
+ */
+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 : `${trimmed}/v1`;
+};
+
 export interface Config {
   readonly apiKey: Redacted.Redacted<string>;
   readonly apiBaseUrl: string;
@@ -26,7 +53,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 +67,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,6 +29,7 @@ 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
@@ -52,6 +53,44 @@ export class FlyIoParseError extends Schema.TaggedError<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,44 @@
  * `./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,
   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";