Integrate Darkship with a coding agent

$ npm install @openfeature/server-sdk

import {
  ErrorCode,
  StandardResolutionReasons,
  type EvaluationContext,
  type JsonValue,
  type Provider,
  type ResolutionDetails,
} from '@openfeature/server-sdk';

type Wire = {
  value: JsonValue;
  variation_key: string | null;
  reason: 'OFF' | 'TARGET_MATCH' | 'RULE_MATCH' | 'FALLTHROUGH' | 'ERROR';
  error_code?: string;
  bucket?: number;
  flag_type?: 'boolean' | 'string' | 'int' | 'float' | 'json' | 'date';
};

export interface DarkshipProviderOptions {
  /** Evaluation host, e.g. https://sdk.darkship.tech (no trailing path). */
  baseUrl: string;
  /** Client key (ds_cli_...). Remote evaluation only accepts client keys. */
  clientKey: string;
  timeoutMs?: number;
  /** How long the flags resolved for one context are reused. */
  cacheTtlMs?: number;
}

const MAX_CACHED_CONTEXTS = 1000;

/** OpenFeature context -> wire context: `targetingKey` becomes `key`, Dates become ISO strings. */
function toWireContext(ctx: EvaluationContext): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(ctx)) {
    if (k === 'targetingKey' || v === undefined) continue;
    out[k] = v instanceof Date ? v.toISOString() : v;
  }
  if (typeof ctx.targetingKey === 'string' && ctx.targetingKey !== '') out.key = ctx.targetingKey;
  return out;
}

function mapReason(w: Wire): string {
  switch (w.reason) {
    case 'OFF': return StandardResolutionReasons.STATIC;
    case 'TARGET_MATCH':
    case 'RULE_MATCH': return w.bucket === undefined ? StandardResolutionReasons.TARGETING_MATCH : StandardResolutionReasons.SPLIT;
    case 'FALLTHROUGH': return w.bucket === undefined ? StandardResolutionReasons.DEFAULT : StandardResolutionReasons.SPLIT;
    default: return StandardResolutionReasons.ERROR;
  }
}

export class DarkshipProvider implements Provider {
  readonly metadata = { name: 'darkship-remote' } as const;
  readonly runsOn = 'server' as const;

  private readonly cache = new Map<string, { at: number; flags: Promise<Record<string, Wire>> }>();

  constructor(private readonly opts: DarkshipProviderOptions) {}

  resolveBooleanEvaluation(key: string, def: boolean, ctx: EvaluationContext) {
    return this.resolve(key, def, ctx, (w) => typeof w.value === 'boolean');
  }
  resolveStringEvaluation(key: string, def: string, ctx: EvaluationContext) {
    return this.resolve(key, def, ctx, (w) => typeof w.value === 'string');
  }
  resolveNumberEvaluation(key: string, def: number, ctx: EvaluationContext) {
    return this.resolve(key, def, ctx, (w) => typeof w.value === 'number');
  }
  resolveObjectEvaluation<T extends JsonValue>(key: string, def: T, ctx: EvaluationContext) {
    return this.resolve(key, def, ctx, (w) => typeof w.value === 'object' && w.value !== null);
  }

  private async resolve<T extends JsonValue>(
    flagKey: string,
    def: T,
    ctx: EvaluationContext,
    matchesType: (w: Wire) => boolean,
  ): Promise<ResolutionDetails<T>> {
    const fail = (errorCode: ErrorCode, errorMessage: string): ResolutionDetails<T> => ({
      value: def,
      reason: StandardResolutionReasons.ERROR,
      errorCode,
      errorMessage,
    });
    let flags: Record<string, Wire>;
    try {
      flags = await this.flagsFor(ctx);
    } catch (err) {
      return fail(ErrorCode.GENERAL, `darkship: evaluation request failed (${(err as Error).message})`);
    }
    const w = Object.hasOwn(flags, flagKey) ? flags[flagKey] : undefined;
    if (w === undefined || w.error_code === 'FLAG_NOT_FOUND') {
      return fail(ErrorCode.FLAG_NOT_FOUND, `darkship: flag "${flagKey}" not found, or not enabled for client-side use`);
    }
    if (w.reason === 'ERROR') return fail(w.error_code === 'INVALID_CONTEXT' ? ErrorCode.INVALID_CONTEXT : ErrorCode.GENERAL, `darkship: ${w.error_code ?? 'error'}`);
    if (!matchesType(w)) return fail(ErrorCode.TYPE_MISMATCH, `darkship: flag "${flagKey}" is a ${w.flag_type ?? 'different'} flag`);
    return {
      value: w.value as T,
      variant: w.variation_key ?? undefined,
      reason: mapReason(w),
      flagMetadata: { ...(w.flag_type ? { flagType: w.flag_type } : {}), ...(w.bucket !== undefined ? { bucket: w.bucket } : {}) },
    };
  }

  /** All client-visible flags for one context, cached briefly and shared by concurrent callers. */
  private flagsFor(ctx: EvaluationContext): Promise<Record<string, Wire>> {
    const wireCtx = toWireContext(ctx);
    const cacheKey = JSON.stringify(Object.entries(wireCtx).sort(([a], [b]) => a.localeCompare(b)));
    const hit = this.cache.get(cacheKey);
    if (hit && Date.now() - hit.at < (this.opts.cacheTtlMs ?? 10_000)) return hit.flags;
    const flags = this.fetchFlags(wireCtx);
    this.cache.set(cacheKey, { at: Date.now(), flags });
    flags.catch(() => this.cache.delete(cacheKey)); // never cache a failure
    if (this.cache.size > MAX_CACHED_CONTEXTS) this.cache.delete(this.cache.keys().next().value as string);
    return flags;
  }

  private async fetchFlags(context: Record<string, unknown>): Promise<Record<string, Wire>> {
    const res = await fetch(`${this.opts.baseUrl.replace(/\/+$/, '')}/v1/sdk/evaluate`, {
      method: 'POST',
      headers: { authorization: `Bearer ${this.opts.clientKey}`, 'content-type': 'application/json' },
      body: JSON.stringify({ context }),
      signal: AbortSignal.timeout(this.opts.timeoutMs ?? 2000),
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return ((await res.json()) as { flags: Record<string, Wire> }).flags;
  }
}

import { OpenFeature } from '@openfeature/server-sdk';
import { DarkshipProvider } from './lib/darkship-provider';

await OpenFeature.setProviderAndWait(
  new DarkshipProvider({
    baseUrl: process.env.DARKSHIP_BASE_URL!,
    clientKey: process.env.DARKSHIP_CLIENT_KEY!,
  }),
);

const flags = OpenFeature.getClient();

// Per request: stable targetingKey + the attributes your rules use.
const useNewCheckout = await flags.getBooleanValue(
  'new-checkout-flow',
  false, // safe default: the old behaviour
  { targetingKey: user.id, plan: user.plan, orgId: org.id },
);

$ npm install @openfeature/web-sdk

import {
  ErrorCode,
  StandardResolutionReasons,
  type EvaluationContext,
  type JsonValue,
  type Provider,
  type ResolutionDetails,
} from '@openfeature/web-sdk';

type Wire = {
  value: JsonValue;
  variation_key: string | null;
  reason: 'OFF' | 'TARGET_MATCH' | 'RULE_MATCH' | 'FALLTHROUGH' | 'ERROR';
  error_code?: string;
  bucket?: number;
  flag_type?: string;
};

export interface DarkshipWebProviderOptions {
  baseUrl: string;
  /** Public client key (ds_cli_...). Never a server key (ds_srv_...). */
  clientKey: string;
  timeoutMs?: number;
}

function toWireContext(ctx: EvaluationContext): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(ctx)) {
    if (k === 'targetingKey' || v === undefined) continue;
    out[k] = v instanceof Date ? v.toISOString() : v;
  }
  if (typeof ctx.targetingKey === 'string' && ctx.targetingKey !== '') out.key = ctx.targetingKey;
  return out;
}

/**
 * Web providers resolve synchronously, so the flags for the current context are fetched in advance:
 * once in initialize() and again whenever the context changes (OpenFeature.setContext).
 */
export class DarkshipWebProvider implements Provider {
  readonly metadata = { name: 'darkship-web' } as const;
  readonly runsOn = 'client' as const;
  private flags: Record<string, Wire> = {};

  constructor(private readonly opts: DarkshipWebProviderOptions) {}

  async initialize(context?: EvaluationContext): Promise<void> {
    await this.load(context ?? {});
  }

  async onContextChange(_old: EvaluationContext, next: EvaluationContext): Promise<void> {
    await this.load(next);
  }

  resolveBooleanEvaluation(key: string, def: boolean) {
    return this.resolve(key, def, (w) => typeof w.value === 'boolean');
  }
  resolveStringEvaluation(key: string, def: string) {
    return this.resolve(key, def, (w) => typeof w.value === 'string');
  }
  resolveNumberEvaluation(key: string, def: number) {
    return this.resolve(key, def, (w) => typeof w.value === 'number');
  }
  resolveObjectEvaluation<T extends JsonValue>(key: string, def: T) {
    return this.resolve(key, def, (w) => typeof w.value === 'object' && w.value !== null);
  }

  private resolve<T extends JsonValue>(flagKey: string, def: T, matchesType: (w: Wire) => boolean): ResolutionDetails<T> {
    const fail = (errorCode: ErrorCode, errorMessage: string): ResolutionDetails<T> => ({
      value: def,
      reason: StandardResolutionReasons.ERROR,
      errorCode,
      errorMessage,
    });
    const w = Object.hasOwn(this.flags, flagKey) ? this.flags[flagKey] : undefined;
    if (w === undefined || w.error_code === 'FLAG_NOT_FOUND') {
      return fail(ErrorCode.FLAG_NOT_FOUND, `darkship: flag "${flagKey}" not found, or not enabled for client-side use`);
    }
    if (w.reason === 'ERROR') return fail(ErrorCode.GENERAL, `darkship: ${w.error_code ?? 'error'}`);
    if (!matchesType(w)) return fail(ErrorCode.TYPE_MISMATCH, `darkship: flag "${flagKey}" is a ${w.flag_type ?? 'different'} flag`);
    const reason =
      w.reason === 'OFF' ? StandardResolutionReasons.STATIC
      : w.bucket !== undefined ? StandardResolutionReasons.SPLIT
      : w.reason === 'FALLTHROUGH' ? StandardResolutionReasons.DEFAULT
      : StandardResolutionReasons.TARGETING_MATCH;
    return { value: w.value as T, variant: w.variation_key ?? undefined, reason };
  }

  private async load(context: EvaluationContext): Promise<void> {
    const res = await fetch(`${this.opts.baseUrl.replace(/\/+$/, '')}/v1/sdk/evaluate`, {
      method: 'POST',
      headers: { authorization: `Bearer ${this.opts.clientKey}`, 'content-type': 'application/json' },
      body: JSON.stringify({ context: toWireContext(context) }),
      signal: AbortSignal.timeout(this.opts.timeoutMs ?? 3000),
    });
    // Throwing here puts the provider in the ERROR state; every resolution then returns the caller's default.
    if (!res.ok) throw new Error(`darkship: evaluation request failed (HTTP ${res.status})`);
    this.flags = ((await res.json()) as { flags: Record<string, Wire> }).flags;
  }
}

import { OpenFeature } from '@openfeature/web-sdk';
import { DarkshipWebProvider } from './lib/darkship-web-provider';

await OpenFeature.setContext({ targetingKey: user.id, plan: user.plan });
await OpenFeature.setProviderAndWait(
  new DarkshipWebProvider({
    baseUrl: import.meta.env.VITE_DARKSHIP_BASE_URL, // https://sdk.darkship.tech
    clientKey: import.meta.env.VITE_DARKSHIP_CLIENT_KEY, // ds_cli_...
  }),
);

const flags = OpenFeature.getClient();
const showBanner = flags.getBooleanValue('promo-banner', false);

// After the user changes (sign-in, plan change), reload the flags:
await OpenFeature.setContext({ targetingKey: newUser.id, plan: newUser.plan });

$ pip install openfeature-sdk

from __future__ import annotations

import json
import time
import urllib.error
import urllib.request
from typing import Any, Callable, Optional, Sequence, Union

from openfeature.evaluation_context import EvaluationContext
from openfeature.exception import FlagNotFoundError, GeneralError, InvalidContextError, TypeMismatchError
from openfeature.flag_evaluation import FlagResolutionDetails, Reason
from openfeature.hook import Hook
from openfeature.provider import AbstractProvider, Metadata

JsonValue = Union[bool, int, float, str, list, dict, None]


class DarkshipProvider(AbstractProvider):
    """OpenFeature provider over the remote evaluation endpoint (client key, ds_cli_...)."""

    def __init__(self, base_url: str, client_key: str, timeout: float = 2.0, cache_ttl: float = 10.0) -> None:
        super().__init__()
        self._url = base_url.rstrip("/") + "/v1/sdk/evaluate"
        self._key = client_key
        self._timeout = timeout
        self._ttl = cache_ttl
        self._cache: dict[str, tuple[float, dict[str, Any]]] = {}

    def get_metadata(self) -> Metadata:
        return Metadata(name="darkship-remote")

    def get_provider_hooks(self) -> list[Hook]:
        return []

    def resolve_boolean_details(self, flag_key: str, default_value: bool, evaluation_context: Optional[EvaluationContext] = None):
        return self._resolve(flag_key, evaluation_context, lambda v: isinstance(v, bool))

    def resolve_string_details(self, flag_key: str, default_value: str, evaluation_context: Optional[EvaluationContext] = None):
        return self._resolve(flag_key, evaluation_context, lambda v: isinstance(v, str))

    def resolve_integer_details(self, flag_key: str, default_value: int, evaluation_context: Optional[EvaluationContext] = None):
        return self._resolve(flag_key, evaluation_context, lambda v: isinstance(v, int) and not isinstance(v, bool))

    def resolve_float_details(self, flag_key: str, default_value: float, evaluation_context: Optional[EvaluationContext] = None):
        return self._resolve(flag_key, evaluation_context, lambda v: isinstance(v, (int, float)) and not isinstance(v, bool))

    def resolve_object_details(self, flag_key: str, default_value: Union[Sequence[JsonValue], dict], evaluation_context: Optional[EvaluationContext] = None):
        return self._resolve(flag_key, evaluation_context, lambda v: isinstance(v, (list, dict)))

    # The SDK turns a raised OpenFeature exception into the caller's default value plus an error code.
    def _resolve(self, flag_key: str, ctx: Optional[EvaluationContext], matches: Callable[[Any], bool]) -> FlagResolutionDetails:
        flags = self._flags_for(ctx)
        flag = flags.get(flag_key)
        if flag is None or flag.get("error_code") == "FLAG_NOT_FOUND":
            raise FlagNotFoundError(f'darkship: flag "{flag_key}" not found, or not enabled for client-side use')
        if flag.get("reason") == "ERROR":
            if flag.get("error_code") == "INVALID_CONTEXT":
                raise InvalidContextError("darkship: INVALID_CONTEXT")
            raise GeneralError(f"darkship: {flag.get('error_code', 'error')}")
        if not matches(flag["value"]):
            raise TypeMismatchError(f'darkship: flag "{flag_key}" is a {flag.get("flag_type", "different")} flag')
        reason = {
            "OFF": Reason.STATIC,
            "TARGET_MATCH": Reason.TARGETING_MATCH,
            "RULE_MATCH": Reason.TARGETING_MATCH,
            "FALLTHROUGH": Reason.DEFAULT,
        }.get(flag["reason"], Reason.UNKNOWN)
        if flag.get("bucket") is not None:
            reason = Reason.SPLIT
        return FlagResolutionDetails(value=flag["value"], variant=flag.get("variation_key"), reason=reason)

    def _flags_for(self, ctx: Optional[EvaluationContext]) -> dict[str, Any]:
        wire: dict[str, Any] = dict(ctx.attributes) if ctx else {}
        if ctx and ctx.targeting_key:
            wire["key"] = ctx.targeting_key
        cache_key = json.dumps(wire, sort_keys=True, default=str)
        hit = self._cache.get(cache_key)
        if hit and time.monotonic() - hit[0] < self._ttl:
            return hit[1]
        request = urllib.request.Request(
            self._url,
            data=json.dumps({"context": wire}, default=str).encode(),
            headers={"authorization": f"Bearer {self._key}", "content-type": "application/json"},
            method="POST",
        )
        try:
            with urllib.request.urlopen(request, timeout=self._timeout) as response:
                flags = json.load(response)["flags"]
        except (urllib.error.URLError, TimeoutError, ValueError) as exc:
            raise GeneralError(f"darkship: evaluation request failed ({exc})") from exc
        if len(self._cache) >= 1000:
            self._cache.pop(next(iter(self._cache)))
        self._cache[cache_key] = (time.monotonic(), flags)
        return flags

import os
from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from darkship_provider import DarkshipProvider

api.set_provider(DarkshipProvider(os.environ["DARKSHIP_BASE_URL"], os.environ["DARKSHIP_CLIENT_KEY"]))
flags = api.get_client()

use_new_checkout = flags.get_boolean_value(
    "new-checkout-flow",
    False,  # safe default: the old behaviour
    EvaluationContext(targeting_key=user.id, attributes={"plan": user.plan, "org_id": org.id}),
)