import type * as cf from "@cloudflare/workers-types";
import * as flagship from "@distilled.cloud/cloudflare/flagship";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Effect from "effect/Effect";
import type * as HttpClient from "effect/http/HttpClient";
import type { Credentials } from "../Credentials.ts";
import {
type EvaluationContext,
type EvaluationDetails,
FlagshipError,
type ReadFlagsClient,
} from "./ReadFlags.ts";
// Shared HTTP scaffolding for the Flagship `ReadFlags` binding. NOT
// re-exported from `index.ts` — only the contract and the impl layers are
// public. A future token-scoped `ReadFlagsHttp` layer reuses this builder with
// an auth minted from an `AccountApiToken`; `ReadFlagsLocal` builds the auth
// from the ambient current-credentials context.
/**
* Injectable auth shared by the Local (current-credentials) impl and a future
* Http (scoped-token) impl. `authorize` discharges the
* `Credentials | HttpClient` requirement of a distilled op; `accountId` is the
* Cloudflare account the ops run against.
*/
export interface FlagshipAuth {
authorize: <A, E>(
eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
) => Effect.Effect<A, E>;
accountId: Effect.Effect<string>;
}
/**
* The HTTP evaluate endpoint only supports a single `targetingKey` query
* param, not the full flat evaluation context the Worker binding accepts.
*/
const targetingKeyOf = (context: EvaluationContext | undefined): string | undefined => {
const value = context?.["targetingKey"];
if (value === undefined) return undefined;
return typeof value === "string" ? value : JSON.stringify(value);
};
/**
* Build a {@link ReadFlagsClient} over the Flagship HTTP evaluate endpoint
* (`GET .../flagship/apps/{appId}/evaluate`).
*
* `appId` is an Effect so the resolution stays deferred to each call — inside
* an Action it resolves through the apply-time RuntimeContext. Mirrors the
* Worker binding's fall-back-to-default semantics: evaluation never fails the
* effect — an HTTP error or a value whose type does not match the requested
* method resolves to `defaultValue` instead. The `raw` runtime binding has no
* HTTP equivalent and dies if used.
*/
export const makeHttpFlagshipClient = (
auth: FlagshipAuth,
appId: Effect.Effect<string>,
): ReadFlagsClient => {
const evaluate = (flagKey: string, context?: EvaluationContext) =>
Effect.all([appId, auth.accountId]).pipe(
Effect.flatMap(([id, accountId]) =>
auth.authorize(
flagship.getAppEvaluate({
accountId,
appId: id,
flagKey,
targetingKey: targetingKeyOf(context),
}),
),
),
);
const details = <T>(
flagKey: string,
defaultValue: T,
match: (value: unknown) => value is T,
context?: EvaluationContext,
): Effect.Effect<EvaluationDetails<T>, FlagshipError, RuntimeContext> =>
evaluate(flagKey, context).pipe(
Effect.map((r): EvaluationDetails<T> =>
match(r.value)
? { flagKey, value: r.value, variant: r.variant, reason: r.reason }
: {
flagKey,
value: defaultValue,
variant: r.variant,
reason: r.reason,
errorCode: "TYPE_MISMATCH",
},
),
Effect.catch((error) =>
Effect.succeed<EvaluationDetails<T>>({
flagKey,
value: defaultValue,
reason: "ERROR",
errorCode: error._tag,
}),
),
);
const value = <T>(
flagKey: string,
defaultValue: T,
match: (value: unknown) => value is T,
context?: EvaluationContext,
): Effect.Effect<T, FlagshipError, RuntimeContext> =>
evaluate(flagKey, context).pipe(
Effect.map((r) => (match(r.value) ? r.value : defaultValue)),
Effect.orElseSucceed(() => defaultValue),
);
const isBoolean = (v: unknown): v is boolean => typeof v === "boolean";
const isString = (v: unknown): v is string => typeof v === "string";
const isNumber = (v: unknown): v is number => typeof v === "number";
const isObjectLike = (v: unknown): boolean => v !== null && typeof v === "object";
return {
// The raw runtime binding is a workerd object with no HTTP surface.
raw: Effect.die(
new FlagshipError({
message:
"the raw Flagship runtime binding is unavailable over HTTP; use ReadFlagsBinding inside a Worker",
cause: undefined,
}),
) as Effect.Effect<cf.Flagship, never, RuntimeContext>,
get: (flagKey, defaultValue, context) =>
evaluate(flagKey, context).pipe(
Effect.map((r) => r.value ?? defaultValue),
Effect.orElseSucceed(() => defaultValue),
),
getBooleanValue: (flagKey, defaultValue, context) =>
value(flagKey, defaultValue, isBoolean, context),
getStringValue: (flagKey, defaultValue, context) =>
value(flagKey, defaultValue, isString, context),
getNumberValue: (flagKey, defaultValue, context) =>
value(flagKey, defaultValue, isNumber, context),
getObjectValue: (flagKey, defaultValue, context) =>
evaluate(flagKey, context).pipe(
Effect.map((r) =>
isObjectLike(r.value) ? (r.value as typeof defaultValue) : defaultValue,
),
Effect.orElseSucceed(() => defaultValue),
),
getBooleanDetails: (flagKey, defaultValue, context) =>
details(flagKey, defaultValue, isBoolean, context),
getStringDetails: (flagKey, defaultValue, context) =>
details(flagKey, defaultValue, isString, context),
getNumberDetails: (flagKey, defaultValue, context) =>
details(flagKey, defaultValue, isNumber, context),
getObjectDetails: (flagKey, defaultValue, context) =>
evaluate(flagKey, context).pipe(
Effect.map((r): EvaluationDetails<typeof defaultValue> =>
isObjectLike(r.value)
? {
flagKey,
value: r.value as typeof defaultValue,
variant: r.variant,
reason: r.reason,
}
: {
flagKey,
value: defaultValue,
variant: r.variant,
reason: r.reason,
errorCode: "TYPE_MISMATCH",
},
),
Effect.catch((error) =>
Effect.succeed<EvaluationDetails<typeof defaultValue>>({
flagKey,
value: defaultValue,
reason: "ERROR",
errorCode: error._tag,
}),
),
),
} satisfies ReadFlagsClient;
};