@ledable/sdk/app

function account<
  const S extends Common & {
    readonly platform: "github" | "todoist" | "youtube" | "spotify";
  },
>(spec: S)

function assetsPrefix(appId: string, version: string): string

function boolean<const S extends Common & { readonly default?: boolean }>(spec: S)

function bundleKey(appId: string, version: string): string

function cacheTag(...parts: readonly unknown[]): Promise<string>

function colorRgb<
  const S extends Common & { readonly default?: readonly [number, number, number] },
>(spec: S)

function colorRgba<
  const S extends Common & { readonly default?: readonly [number, number, number, number] },
>(spec: S)

function country<const S extends Common & { readonly default?: string }>(spec: S)

function createAppCache(backend: CacheBackend, scope: AppCacheScope): AppCache

function createAppServer(options: AppServerOptions): FetchHandler

function createRng(seed: number): Rng

function credential<const S extends Common>(spec: S)

function date<const S extends Common & { readonly default?: string }>(spec: S)

function datetime<const S extends Common & { readonly default?: number }>(spec: S)

function defineApp<S extends Settings>(app: AppDefinition<S>): LedApp

function fixedNumber(value: number, digits = 0): string

function float<const S extends Common & { readonly default?: number }>(spec: S)

function hostApp(app: LedApp, manifest: AppManifest): HostedApp

function integer<const S extends Common & { readonly default?: number }>(spec: S)

function listingProblems(listing: Pick<
  ReleaseManifest, "name" | "description" | "description_long" | "tags" | "screenshots"
>): string[]

function location<const S extends Common & { readonly default?: LocationValue }>(spec: S)

function manifestKey(appId: string, version: string): string

function manifestToPublicDict(
  manifest: AppManifest,
  baseUrl: string,
  endpoint: string,
): PublicManifest

function marquee(options: MarqueeOptions): Marquee

function memoryCacheBackend(now: () => number = Date.now): CacheBackend

function multiselect<
  const S extends Common & {
    readonly default?: readonly string[];
    readonly options: readonly string[];
  },
>(spec: S)

function outboundRefusal(url: URL, network: AppNetwork): string | null

function parseFields(
  raw: Readonly<Record<string, string>>,
  fields: Readonly<Record<string, ConfigField>>,
): AppParams

function parseFieldValue(field: ConfigField, raw: string): ConfigValue

async function readSettings(
  app: HostedApp,
  endpoint: string,
  manifest: AppManifest,
  cacheBackend: CacheBackend,
  capabilities: SettingsCapabilities,
): Promise<ProjectSettings>

async function resultWebpBlob(
  image: ResultImage | null | undefined,
  frameMs: number,
  behavior: AnimationBehavior,
  encoder?: FrameEncoder,
): Promise<Uint8Array | null>

function select<const S extends SelectSpec>(spec: S)

function significantNumber(value: number, digits = 4): string

function stableStringify(value: unknown): string

function staticConfigSource(values: Readonly<Record<string, string>>): ConfigSource

function string<const S extends Common & { readonly default?: string }>(spec: S)

function time<const S extends Common & { readonly default?: string }>(spec: S)

function timezone<const S extends Common & { readonly default?: string }>(spec: S)

async function verifyAppCredential(
  app: HostedApp,
  endpoint: string,
  credential: CredentialToVerify,
  secretsPool: Readonly<Record<string, string>>,
): Promise<CredentialVerdict | null>

function versionId(appId: string, version: string): string

const APP_CATEGORIES = [
  "clock",
  "weather",
  "finance",
  "news",
  "sports",
  "productivity",
  "developer",
  "entertainment",
  "science",
  "travel",
] as const

const appCategorySchema = z.enum(APP_CATEGORIES)

const appIdSchema = z.string().check(z.regex(/^[a-z0-9][a-z0-9-]{0,63}$/))

const appManifestSchema

const assetPathSchema = z
  .string()
  .check(
    z.maxLength(256),
    z.regex(new RegExp(`^${ASSET_SEGMENT}(/${ASSET_SEGMENT})*\\.(${ASSET_EXTENSIONS})$`)),
  )

const assetRefSchema = z.object({ path: assetPathSchema })

const credentialVerdictSchema = z.union([
  z.object({ valid: z.literal(true) }),
  z.object({ valid: z.literal(false), message: z.string() }),
])

const DEFAULT_FRAME_MS = 200

const DEFAULT_HARD_TTL_MS = 10 * 60 * 1000

const DEFAULT_MARQUEE_FPS = 50

const DEFAULT_SETTINGS_TTL_MS = 24 * 60 * 60 * 1000

const DEFAULT_SOFT_TTL_MS = 5 * 60 * 1000

const hostPatternSchema = z.string().check(
  z.refine(pattern => {
    const name = pattern.startsWith("*.") ? pattern.slice(2) : pattern;
    return name.length <= 253 && HOST_NAME.test(name);
  }, "Use a lowercase host name, or *. and a host name, without scheme, port or path"),
  z.refine(
    pattern => !pattern.startsWith("*.") || !isPublicSuffix(pattern.slice(2)),
    "A wildcard must not cover a public suffix such as *.com",
  ),
)

const LISTING_LIMITS = {
  name: 30,
  description: 120,
  readme: 4000,
  tags: 5,
  tag: 20,
  screenshots: 6,
} as const

const locationValueSchema

const MAX_MARQUEE_FRAMES = 600

const networkSchema

const newsResponseSchema = z.extend(newsSummarySchema, {
  counts: z.record(z.string(), z.int().check(z.nonnegative())),
})

const newsSummarySchema = z.object({
  items: z.array(z.string()),
})

const numericSchema = z.pipe(
  z.union([
    z.number(),
    z.pipe(z.string().check(z.trim(), z.regex(decimalText)), z.transform(Number)),
  ]),
  z.number(),
)

const previewResultSchema = z.extend(
  z.pick(renderResultSchema, { frameMs: true, behavior: true }),
  { image: z.nullish(resultImageSchema) },
)

const PROJECT_FILE = "ledable.json"

const projectFieldSchema

const projectSchema

const publicManifestSchema

const queryConfigSource: ConfigSource = ({ request }) => {
  const raw: Record<string, string> = {};
  for (const [key, value] of new URL(request.url).searchParams) {
    raw[key] = value;
  }
  return raw;
}

const releaseManifestSchema

const renderResultSchema = z.object({
  ok: z.optional(z.boolean()),
  msg: optionalString,
  image: z.optional(z.nullable(resultImageSchema)),
  frameMs: z.optional(z.number()),
  behavior: z.optional(animationBehaviorSchema),
  realtime: z.optional(z.boolean()),
  softTtlMs: z.optional(z.number()),
  hardTtlMs: z.optional(z.number()),
  cacheId: optionalString,
})

const REQ_HEADER_CACHE_ID = "LD-Cache-ID"

const REQ_HEADER_DURATION = "LD-Duration"

const REQ_HEADER_FIRMWARE = "LD-Firmware"

const REQ_HEADER_INSTANCE = "LD-Instance"

const REQ_HEADER_LANGUAGE = "LD-Language"

const REQ_HEADER_MODEL = "LD-Model"

const REQ_HEADER_RESOLUTION = "LD-Resolution"

const REQ_HEADER_TIMEZONE = "LD-Timezone"

const RESP_HEADER_BEHAVIOR = "LD-Behavior"

const RESP_HEADER_CACHE_ID = "LD-Cache-ID"

const RESP_HEADER_HARD_TTL = "LD-Hard-TTL"

const RESP_HEADER_REALTIME = "LD-Realtime"

const RESP_HEADER_SOFT_TTL = "LD-Soft-TTL"

const secretNameSchema = z.string().check(z.regex(/^[A-Z_][A-Z0-9_]*$/))

const settingsSchema

const versionSchema = z
  .string()
  .check(z.regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,32})?$/))

class ConfigError extends Error

interface AppAssets {
  /** Raw bytes of any asset, e.g. a `.ledfont` for `decodeBitmapFont`. */
  bytes(ref: AssetRef): Promise<Uint8Array>;
  /** Decoded pixels of a still WebP asset; for an animation, its first frame. */
  image(ref: AssetRef): Promise<Framebuffer>;
  /** Every frame of a WebP asset in order; a still asset yields exactly one. */
  frames(ref: AssetRef): Promise<readonly Framebuffer[]>;
}

interface AppAuth {
  /** Current provider access token, or null when authorization is required. */
  getToken(handle: string): Promise<string | null>;
}

interface AppCache {
  /** `tag` names the call site (e.g. "quote", "webp") within the app. */
  get<T>(tag: string, compute: () => Promise<CacheEntry<T>>, options?: CacheGetOptions): Promise<T>;
}

interface AppCacheScope {
  /** Endpoint name; part of the hard namespace prefix. */
  readonly appId: string;
  /** Manifest version; keys never survive an app version bump. */
  readonly version: string;
  readonly fields: readonly string[];
  readonly params: AppParams;
}

interface AppCredentials {
  /** The value a credential setting's handle names, or null once it is deleted. */
  get(handle: string): Promise<string | null>;
}

interface AppImages {
  /** Decode bounded upstream JPEG or PNG image bytes through the host's WASM codecs. */
  decode(bytes: Uint8Array): Promise<Framebuffer>;
}

interface AppLocations {
  /** Resolve coordinates with the platform's versioned geographic timezone dataset. */
  timezoneAt(lat: number, lng: number): Promise<string | null>;
}

interface AppNews {
  /** Shared news summaries; provider credentials stay in the host service. */
  getSummary(): Promise<NewsResponse>;
}

interface AppServerOptions {
  readonly apps: Readonly<Record<string, HostedApp>>;
  readonly configSource?: ConfigSource;
  /** Frame compressor for WebP output; defaults to the pure-TS encoder. */
  readonly frameEncoder?: FrameEncoder;
  /**
   * Storage behind ctx.cache, the settings and the encoded WebP; the host decides where entries
   * live and how widely they are shared.
   */
  readonly cacheBackend: CacheBackend;
  /**
   * Pool of platform-held secrets available to the hosted apps. Each app only
   * ever sees the names its manifest declares.
   */
  readonly secrets?: Readonly<Record<string, string>>;
  readonly auth?: AppAuth;
  /** The credentials users typed into the hosted apps' credential settings. */
  readonly credentials?: AppCredentials;
  readonly news?: AppNews;
  readonly locations?: AppLocations;
  readonly images?: AppImages;
  /** Asset store of the hosted bundle version; previews read it too. */
  readonly assets?: AppAssets;
  readonly serverName?: string;
}

interface AssetRef {
  /**
   * Path inside this version's assets: where the file sits in its project, e.g.
   * `assets/sun.webp`, or `sdk/<package>/…` for a file of an SDK package.
   */
  readonly path: string;
}

interface CacheBackend {
  get(key: string): Promise<CachedValue | null>;
  put(key: string, value: CachedValue, ttlMs: number): Promise<void>;
}

interface CachedValue {
  readonly kind: CachedKind;
  readonly bytes: Uint8Array;
}

interface CacheEntry<T> {
  readonly value: T;
  readonly ttlMs: number;
}

interface CacheGetOptions {
  /**
   * Manifest field names the cached value depends on. Omitted = all fields
   * (fully isolated per distinct config, the safe default). Narrowing to a
   * subset is what enables cross-user sharing.
   */
  readonly vary?: readonly string[];
}

interface CredentialToVerify {
  readonly field: string;
  readonly value: string;
}

interface HostedApp {
  readonly manifest: AppManifest;
  settings(ctx: SettingsContext): Promise<HostedSettings>;
  render(ctx: RenderContext, params: AppParams): RenderResult | Promise<RenderResult>;
  preview(ctx: PreviewContext): PreviewResult | Promise<PreviewResult>;
  /** The app's check of a credential, unchecked; null for a bundle without one. */
  verifyCredential(ctx: VerifyContext, credential: CredentialToVerify): Promise<unknown>;
}

interface HostedSettings {
  readonly fields: unknown;
  readonly ttlMs: number;
}

interface LedApp<Params = AppParams> {
  /** Every setting the app has, as manifest fields (./settings.ts). */
  settings(ctx: SettingsContext): Settings | Promise<Settings>;
  /** How long the platform keeps what `settings` returned; a day unless the app says. */
  readonly settingsTtlMs?: number | undefined;
  render(ctx: RenderContext, params: Params): RenderResult | Promise<RenderResult>;
  /** Must be deterministic and must not perform network requests. */
  preview(ctx: PreviewContext): PreviewResult | Promise<PreviewResult>;
  readonly verifyCredential?: CredentialCheck | undefined;
}

interface Marquee {
  readonly frameCount: number;
  readonly frameMs: number;
  /** Scroll offset in px for a 0-based frame; last frame reaches distancePx. */
  offsetAt(frame: number): number;
}

interface MarqueeOptions {
  /** Total scroll distance in px (typically content width + viewport width). */
  readonly distancePx: number;
  readonly durationMs: number;
  readonly fps?: number;
}

interface PreviewContext {
  readonly assets: AppAssets;
}

interface RenderContext {
  readonly auth: AppAuth;
  readonly credentials: AppCredentials;
  readonly news: AppNews;
  readonly locations: AppLocations;
  readonly images: AppImages;
  /** Published WebP assets of this bundle version. */
  readonly assets: AppAssets;
  /** Device model name (LD-Model). */
  readonly model: string;
  /** Screen resolution in pixels (LD-Resolution). */
  readonly resolution: readonly [number, number];
  /** Firmware version (LD-Firmware). */
  readonly firmware: string;
  /** Unique ID for this app instance (LD-Instance). */
  readonly instanceId: string;
  /** Previous cache ID for this app instance (LD-Cache-ID). */
  readonly cacheId: string;
  /** Language code (LD-Language). */
  readonly language: string;
  /** IANA TZ identifier (LD-Timezone). */
  readonly timezone: string;
  /** Display duration of this app in milliseconds (LD-Duration). */
  readonly durationMs: number;
  /**
   * Server-assigned render instant. Apps must read wall-clock time from here
   * (not Date.now()) so tests can pin it; preview() must not use time at all.
   */
  readonly now: Date;
  /**
   * Read-through compute cache, keyed by the framework from the app's parsed
   * params (all fields by default; narrow with `vary` to share). preview()
   * has no cache — previews are deterministic and memoized by the server.
   */
  readonly cache: AppCache;
  /** Platform-provisioned secrets, restricted to the manifest declaration. */
  readonly secrets: Readonly<Record<string, string>>;
}

interface Rng {
  /** Uniform float in [0, 1). */
  next(): number;
  /** Uniform integer in [0, maxExclusive). */
  int(maxExclusive: number): number;
  /** New array with the items in shuffled order (Fisher-Yates). */
  shuffle<T>(items: readonly T[]): T[];
  /** `count` distinct items in draw order. */
  sample<T>(items: readonly T[], count: number): T[];
}

interface SettingsContext {
  readonly now: Date;
  readonly cache: AppCache;
  readonly secrets: Readonly<Record<string, string>>;
  readonly assets: AppAssets;
}

interface VerifyContext {
  readonly now: Date;
  readonly secrets: Readonly<Record<string, string>>;
}

type AnimationBehavior = z.infer<typeof animationBehaviorSchema>;

type AppCategory = z.infer<typeof appCategorySchema>;

type AppDefinition<S extends Settings> = AppBase<S> &
  (HasCredential<S> extends true ? { readonly verifyCredential: CredentialCheck } : unknown);

type AppManifest = Readonly<z.infer<typeof appManifestSchema>>;

type AppNetwork = z.infer<typeof networkSchema>;

type AppParams = z.infer<typeof appParamsSchema>;

type AppVisibility = z.infer<typeof appVisibilitySchema>;

type ConfigField = Readonly<z.infer<typeof configFieldSchema>>;

type ConfigSource = (input: {
  readonly request: Request;
  readonly endpoint: string;
  /** Context before platform capabilities and parsed params are available. */
  readonly ctx: BaseContext;
}) => Record<string, string> | Promise<Record<string, string>>;

type ConfigValue = z.infer<typeof configValueSchema>;

type ConfigValueType = z.infer<typeof configValueTypeSchema>;

type CredentialVerdict = Readonly<z.infer<typeof credentialVerdictSchema>>;

type DateValue = Readonly<z.infer<typeof dateValueSchema>>;

type FetchHandler = (request: Request) => Promise<Response>;

type Field<Value> = ConfigField & { readonly __value?: Value };

type LocationValue = Readonly<z.infer<typeof locationValueSchema>>;

type NewsResponse = z.infer<typeof newsResponseSchema>;

type ParamsOf<S extends Settings> = {
  readonly [Key in keyof S]: S[Key] extends Field<infer Value>
    ? S[Key] extends { readonly required: true } | { readonly default: unknown }
      ? Value
      : Value | null
    : never;
};

type PreviewResult = Readonly<z.infer<typeof previewResultSchema>>;

type ProjectConfig = z.infer<typeof projectSchema>;

type ProjectField = z.infer<typeof fieldShape>;

type ProjectSettings = z.infer<typeof settingsSchema>;

type PublicManifest = z.infer<typeof publicManifestSchema>;

type ReleaseManifest = z.infer<typeof releaseManifestSchema>;

type RenderResult = Readonly<z.infer<typeof renderResultSchema>>;

type ResultImage = z.infer<typeof resultImageSchema>;

type Settings = Readonly<Record<string, Field<unknown>>>;

type TimeValue = Readonly<z.infer<typeof timeValueSchema>>;