@flaredev/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,438 @@
+import { F as Field, C as CreateInput, U as UpdateInput, R as Resource, S as StoredField } from './define-D5CtCkOm.js';
+export { B as BelongsToField, a as BooleanField, D as DEFAULT_FILE_MAX_BYTES, b as DateField, c as DateTimeField, E as EnumField, d as FILE_CATEGORIES, e as FieldKind, f as FieldValue, g as FileCategory, h as FileField, i as FloatField, H as HasManyField, I as IntField, j as RESERVED_FIELD_NAMES, k as RecordOf, l as ResourceConfig, m as ResourceDefinitionError, n as StringField, T as TextField, o as columnName, p as defaultFieldLabel, q as defineResource, r as field, s as fileMaxBytes, t as mimeTypesFor, u as storedFields } from './define-D5CtCkOm.js';
+import { z } from 'zod';
+
+/**
+ * Password hashing for Workers.
+ *
+ * Better Auth's default scrypt runs in pure JavaScript and costs ~250-300ms of
+ * CPU per hash, far over the Workers free-plan CPU limit. PBKDF2-SHA256 through
+ * WebCrypto runs natively and is several times cheaper. 100,000 iterations is
+ * the maximum Workers' WebCrypto accepts.
+ *
+ * Stored format: `pbkdf2-sha256$<iterations>$<base64 salt>$<base64 hash>`.
+ * The iteration count is read back from the stored hash, so it can be raised
+ * later without breaking existing passwords.
+ */
+declare const PBKDF2_ITERATIONS = 100000;
+declare function hashPassword(password: string): Promise<string>;
+declare function verifyPassword({ hash, password }: {
+    hash: string;
+    password: string;
+}): Promise<boolean>;
+
+/**
+ * Import an HMAC key for one purpose. The purpose label is mixed in so the same
+ * app secret (e.g. BETTER_AUTH_SECRET) yields unrelated keys for unrelated uses.
+ */
+declare function importSigningKey(secret: string, purpose: string): Promise<CryptoKey>;
+declare function signToken(key: CryptoKey, payload: object): Promise<string>;
+/** Returns the payload when the signature is valid, otherwise null. Does not check expiry. */
+declare function verifyToken<T>(key: CryptoKey, token: string): Promise<T | null>;
+
+/**
+ * Transactional email through Resend's REST API (plain fetch, no SDK).
+ *
+ * Like the official SDK, `send` never throws for API failures: it resolves to
+ * `{ data, error }`. Transient failures (429, 5xx, concurrent idempotent request)
+ * are retried with backoff, but only when an idempotency key is given, so a retry
+ * can never deliver a duplicate.
+ */
+interface MailMessage {
+    to: string | string[];
+    subject: string;
+    html: string;
+    text?: string;
+    replyTo?: string | string[];
+    /** Overrides the mailer's default sender. */
+    from?: string;
+    /** e.g. `password-reset/<userId>/<tokenId>`. Required for retries; 1-256 chars; valid for 24h. */
+    idempotencyKey?: string;
+}
+type MailResult = {
+    data: {
+        id: string;
+    };
+    error: null;
+} | {
+    data: null;
+    error: {
+        name: string;
+        message: string;
+        statusCode: number | null;
+    };
+};
+interface MailerOptions {
+    /** Resend API key. When empty, messages are logged instead of sent (local development). */
+    apiKey: string | undefined;
+    /** Default sender, e.g. `Acme <hello@acme.com>`. The domain must be verified in Resend. */
+    from: string;
+    /** Retries after the first attempt, for transient failures. Default 2. */
+    maxRetries?: number;
+    fetch?: typeof fetch;
+    /** Where logged (key-less) messages go. Default console.info. */
+    log?: (message: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+declare function createMailer(options: MailerOptions): {
+    send: (message: MailMessage) => Promise<MailResult>;
+};
+type Mailer = ReturnType<typeof createMailer>;
+interface TransactionalEmail {
+    /** Product name shown above the heading. */
+    appName: string;
+    heading: string;
+    /** Plain-text paragraphs; HTML is escaped. */
+    paragraphs: string[];
+    action?: {
+        label: string;
+        url: string;
+    };
+    /** Small print under the content, e.g. "If you didn't request this, ignore this email." */
+    footer?: string;
+    /** Inbox preview text. */
+    preheader?: string;
+}
+/**
+ * A plain, monochrome transactional email (table layout with inline styles, which
+ * email clients need). Returns both HTML and text parts.
+ */
+declare function renderTransactionalEmail(email: TransactionalEmail): {
+    html: string;
+    text: string;
+};
+
+/**
+ * Signed upload/read URLs for an R2 bucket binding.
+ *
+ * Bindings can't produce S3 presigned URLs, so Flare signs its own: a short-lived
+ * HMAC token scoped to one operation and one object key, redeemed by a Worker
+ * route (`app/api/storage/route.ts`) that streams through the binding. No R2 API
+ * credentials or bucket CORS are needed, and it behaves the same in local dev.
+ * Trade-off: bytes pass through the Worker, so uploads are capped by the Workers
+ * request body limit (100 MB on the free plan).
+ *
+ * Tokens authorize the holder, so only issue them after checking the current user
+ * may upload or read that key.
+ */
+/** The subset of the R2Bucket binding this module uses (keeps core free of workers-types). */
+interface StorageBucket {
+    get(key: string): Promise<StorageObjectBody | null>;
+    put(key: string, value: ReadableStream | ArrayBuffer | string | null, options?: {
+        httpMetadata?: {
+            contentType?: string;
+            contentDisposition?: string;
+        };
+    }): Promise<unknown>;
+    delete(keys: string | string[]): Promise<void>;
+}
+interface StorageObjectBody {
+    body: ReadableStream;
+    size: number;
+    httpEtag: string;
+    httpMetadata?: {
+        contentType?: string;
+    };
+}
+interface StorageOptions {
+    bucket: StorageBucket;
+    /** App secret the signing key is derived from (Flare apps pass BETTER_AUTH_SECRET). */
+    secret: string;
+    /** Path of the route that redeems tokens. Default "/api/storage". */
+    routePath?: string;
+    /** Prefix URLs with an origin (e.g. for emails). Default: relative URLs. */
+    baseURL?: string;
+    /** Default token lifetime in seconds. Default 900 (15 minutes). */
+    expiresIn?: number;
+}
+interface UploadUrlOptions {
+    key: string;
+    /** Allowed Content-Type values; "image/*" style wildcards are accepted. */
+    contentTypes: string[];
+    /** Maximum upload size in bytes. */
+    maxBytes: number;
+    expiresIn?: number;
+}
+interface ReadUrlOptions {
+    key: string;
+    expiresIn?: number;
+    /** Serve as an attachment with this filename instead of inline. */
+    downloadAs?: string;
+}
+declare function matchesContentType(contentType: string, allowed: string[]): boolean;
+/** A collision-free object key, e.g. `uploads/2026/09/3f1c…-quarterly-report.pdf`. */
+declare function createObjectKey(filename: string, prefix?: string): string;
+declare function createStorage(options: StorageOptions): {
+    bucket: StorageBucket;
+    /** A URL the browser can PUT the file body to, with the `Content-Type` header set. */
+    createUploadUrl(upload: UploadUrlOptions): Promise<{
+        url: string;
+        method: "PUT";
+        key: string;
+        expiresAt: Date;
+    }>;
+    /** A temporary URL that serves the object. */
+    createReadUrl(read: ReadUrlOptions): Promise<string>;
+    delete: (key: string) => Promise<void>;
+    /** Handles `PUT <routePath>?token=` (upload) and `GET <routePath>?token=` (read). */
+    handleRequest(request: Request): Promise<Response>;
+};
+type Storage = ReturnType<typeof createStorage>;
+
+/**
+ * Content sniffing for uploads: does a file's leading bytes match the type it claims?
+ *
+ * A browser (or anyone with a signed URL) chooses the Content-Type it sends, so a
+ * `file:[image]` field can't rely on the label alone. These checks look at the
+ * signature every real file of the type starts with. Used on the server as the
+ * gate, and in the admin's file widget for instant feedback.
+ */
+/** Bytes needed from the start of a file for every check below. */
+declare const SNIFF_BYTES = 32;
+/**
+ * Whether `head` (the first {@link SNIFF_BYTES} bytes, or the whole file when it's
+ * shorter) looks like `contentType`.
+ *
+ * Returns `undefined` for types with no known signature, so custom types passed to
+ * `createUploadUrl` keep working; `false` means the bytes contradict the label.
+ */
+declare function sniffMatches(contentType: string, head: Uint8Array): boolean | undefined;
+
+/**
+ * Billing decisions shared by the code `flare gen billing` writes into an app.
+ *
+ * Kept here, free of the Stripe SDK and the database, so the rules that decide
+ * what a customer has paid for are unit-tested once instead of living only in
+ * generated templates. The shapes below are the minimal subset of Stripe's
+ * objects the rules read.
+ */
+/** Subscription states a Customer row can hold. */
+declare const SUBSCRIPTION_STATUSES: readonly ["none", "incomplete", "trialing", "active", "past_due", "paused", "canceled", "unpaid"];
+type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];
+/** Whether a status still counts as "has a subscription" (so a second one must not be started). */
+declare const isLiveSubscription: (status: string | null | undefined) => boolean;
+/** Whether a status grants access to paid features. past_due keeps access while Stripe retries. */
+declare const grantsAccess: (status: string | null | undefined) => boolean;
+/** Map a Stripe subscription status onto the app's statuses. */
+declare function toSubscriptionStatus(stripeStatus: string): SubscriptionStatus;
+/** The fields of a Stripe Subscription these rules read. */
+interface SubscriptionLike {
+    id: string;
+    status: string;
+    created: number;
+    cancel_at_period_end?: boolean | null;
+    cancel_at?: number | null;
+    ended_at?: number | null;
+    items?: {
+        data?: Array<{
+            current_period_end?: number | null;
+            price?: {
+                id: string;
+            } | null;
+        }>;
+    } | null;
+}
+/**
+ * When the current paid period ends, in ms. On API versions from 2025-03-31
+ * (basil) onward the period lives on subscription items, not the subscription.
+ */
+declare function currentPeriodEnd(subscription: SubscriptionLike): number | null;
+/** The subscription's (first) price, which maps it to a Plan row. */
+declare const subscriptionPriceId: (subscription: SubscriptionLike) => string | null;
+/** The customer-facing subscription state, derived from a freshly fetched Subscription. */
+interface SubscriptionState {
+    stripeSubscriptionId: string;
+    subscriptionStatus: SubscriptionStatus;
+    /** Renewal date while active; the date access ends when cancelling or ended. */
+    subscriptionEndsAt: Date | null;
+    cancelAtPeriodEnd: boolean;
+    priceId: string | null;
+}
+declare function subscriptionState(subscription: SubscriptionLike): SubscriptionState;
+/**
+ * Whether a subscription's state may overwrite what a Customer row holds.
+ *
+ * Handlers always re-fetch the subscription from Stripe, so the state they write
+ * is current and order no longer matters for a single subscription. What remains
+ * is a customer with more than one: a late event about an old, ended subscription
+ * must not replace a newer live one. So a different subscription only takes over
+ * when it is live itself, or when the stored one no longer is.
+ */
+declare function shouldApplySubscription(stored: {
+    stripeSubscriptionId: string | null;
+    subscriptionStatus: string | null;
+}, incoming: SubscriptionLike): boolean;
+/** A Checkout Session's payment is settled (card now, or a delayed method that has succeeded). */
+declare const checkoutPaid: (session: {
+    payment_status: string;
+}) => boolean;
+/** `8 random lowercase letters`, the suffix Stripe asks for on `integration_identifier`. */
+declare function randomLetters(length?: number): string;
+
+/**
+ * Zod schemas derived from a descriptor at runtime. Unknown keys are rejected,
+ * so clients can't set `id`, timestamps or undeclared columns (no mass assignment).
+ * Messages are written for people (they're shown next to form fields and returned by
+ * the REST API).
+ */
+interface ResourceValidators<Fields extends Record<string, Field>> {
+    create: z.ZodType<CreateInput<Fields>>;
+    update: z.ZodType<UpdateInput<Fields>>;
+}
+declare function fieldSchema(def: StoredField): z.ZodType;
+/**
+ * Where a file field's uploads live: `<table>/<field>/`. The admin issues upload URLs
+ * under this prefix, and a record only accepts keys under it — otherwise anyone who can
+ * edit a record could attach another resource's private file and read it through theirs.
+ */
+declare const fileKeyPrefix: (resource: Pick<Resource, "table">, fieldKey: string) => string;
+declare function createValidators<Fields extends Record<string, Field>>(resource: Resource<Fields>): ResourceValidators<Fields>;
+
+/** Naming helpers shared by descriptors and the generator. */
+/** "OrderItem" / "order item" / "order-item" → ["order", "item"] */
+declare function words(value: string): string[];
+declare const pascalCase: (value: string) => string;
+declare const camelCase: (value: string) => string;
+declare const snakeCase: (value: string) => string;
+declare const kebabCase: (value: string) => string;
+/** "orderItem" → "Order item" */
+declare const humanize: (value: string) => string;
+/** English plural of the last word: "category" → "categories", "OrderItem" → "OrderItems". */
+declare function pluralize(value: string): string;
+
+interface BelongsToRelation {
+    /** Field key on this resource, e.g. "companyId". */
+    key: string;
+    /** Relation accessor name, e.g. "company". */
+    name: string;
+    target: string;
+    required: boolean;
+    onDelete: "cascade" | "restrict" | "set null";
+    /** Stable name shared by both sides (Drizzle `relationName`). */
+    relationName: string;
+}
+interface HasManyRelation {
+    key: string;
+    target: string;
+    /** belongsTo key on the target pointing back here. */
+    foreignKey: string;
+    relationName: string;
+}
+interface ResourceRelations {
+    belongsTo: BelongsToRelation[];
+    hasMany: HasManyRelation[];
+}
+interface RelationGraph {
+    byResource: Record<string, ResourceRelations>;
+    /** hasMany declarations whose target resource doesn't exist yet. */
+    pending: {
+        resource: string;
+        key: string;
+        target: string;
+    }[];
+}
+declare class RelationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve belongsTo/hasMany across all resources. Throws for belongsTo targets that
+ * don't exist and for hasMany declarations without a matching belongsTo on the target.
+ */
+declare function relationGraph(resources: readonly Resource[]): RelationGraph;
+
+/** Semantic tone for a status-like enum value (style-guide status colors). */
+type Tone = "success" | "warning" | "danger" | "neutral";
+declare function statusTone(value: unknown): Tone;
+/** Display label for an enum option: the descriptor's optionLabels, else "on_hold" → "On hold". */
+declare function optionLabel(def: StoredField, value: string): string;
+interface FormatOptions {
+    locale?: string;
+    timeZone?: string;
+}
+/**
+ * A field value as short display text (tables, detail views). Relations and files are
+ * returned as-is (their ids/keys); callers resolve those to titles or links.
+ */
+declare function formatValue(def: StoredField | {
+    kind: "timestamp";
+}, value: unknown, options?: FormatOptions): string;
+
+/**
+ * Form state for a resource: strings for text-like inputs, booleans for toggles.
+ * These helpers convert between records, form state, and API input so every admin
+ * form handles empty values, numbers, and defaults the same way.
+ */
+type FormValues = Record<string, string | boolean>;
+/** Initial form state: the record's values (edit) or the descriptor's defaults (create). */
+declare function initialFormValues(resource: Resource, record?: Record<string, unknown> | null): FormValues;
+/**
+ * API input from form state. Empty optional fields become null (clearing them);
+ * empty fields that have a default are omitted on create so the default applies;
+ * empty required fields are left for validation to report as "Required".
+ */
+declare function formValuesToInput(resource: Resource, values: FormValues, mode: "create" | "edit"): Record<string, unknown>;
+/** Field errors keyed by field name, from validation or API issues (first message wins). */
+declare function issuesByField(issues: {
+    path: string | PropertyKey[];
+    message: string;
+}[]): Record<string, string>;
+
+/**
+ * Resource-level policies: which roles may read, create, update, or delete a resource.
+ *
+ * Policies are plain data, like descriptors, so the API layer and the admin UI read the
+ * same rules at runtime. Field-level rules and per-record ownership are deliberately out
+ * of scope for v1.
+ */
+type PolicyAction = "list" | "read" | "create" | "update" | "delete";
+/** Roles allowed per action; `"*"` means any signed-in user. */
+interface Policy {
+    resource: string;
+    read: string[];
+    create: string[];
+    update: string[];
+    delete: string[];
+}
+interface PolicyConfig {
+    resource: string;
+    read?: string[];
+    create?: string[];
+    update?: string[];
+    delete?: string[];
+}
+declare class PolicyError extends Error {
+    constructor(message: string);
+}
+declare function definePolicy(config: PolicyConfig): Policy;
+/**
+ * Whether `role` may perform `action`. Without a policy any signed-in user is allowed
+ * (callers must already have required a session); generate one with
+ * `flare gen policy <Resource> --roles …` to restrict a resource.
+ */
+declare function can(policy: Policy | undefined | null, role: string | null | undefined, action: PolicyAction): boolean;
+/** Actions `role` may perform, for hiding UI it can't use. */
+declare function allowedActions(policy: Policy | undefined | null, role: string | null | undefined): Record<Exclude<PolicyAction, "list">, boolean>;
+
+/**
+ * Seed files: `seeds/<name>.seed.ts`, run by `flare seed` against the local D1 database.
+ *
+ *   import { defineSeed } from "@flaredev/core";
+ *   import { contacts } from "@/db/schema";
+ *
+ *   export default defineSeed(async ({ db }) => {
+ *     await db.insert(contacts).values([{ name: "Ada", email: "ada@example.com" }]);
+ *   });
+ */
+interface SeedContext {
+    /** Drizzle client over the app's schema, bound to the local D1 database. */
+    db: any;
+    /** All local bindings and variables (D1, R2, .dev.vars). */
+    env: Record<string, unknown>;
+    log: (message: string) => void;
+}
+type Seed = (context: SeedContext) => void | Promise<void>;
+declare function defineSeed(seed: Seed): Seed;
+
+declare const FLARE_VERSION = "0.1.0";
+
+export { type BelongsToRelation, CreateInput, FLARE_VERSION, Field, type FormValues, type FormatOptions, type HasManyRelation, type MailMessage, type MailResult, type Mailer, type MailerOptions, PBKDF2_ITERATIONS, type Policy, type PolicyAction, type PolicyConfig, PolicyError, type ReadUrlOptions, RelationError, type RelationGraph, Resource, type ResourceRelations, type ResourceValidators, SNIFF_BYTES, SUBSCRIPTION_STATUSES, type Seed, type SeedContext, type Storage, type StorageBucket, type StorageOptions, StoredField, type SubscriptionLike, type SubscriptionState, type SubscriptionStatus, type Tone, type TransactionalEmail, UpdateInput, type UploadUrlOptions, allowedActions, camelCase, can, checkoutPaid, createMailer, createObjectKey, createStorage, createValidators, currentPeriodEnd, definePolicy, defineSeed, fieldSchema, fileKeyPrefix, formValuesToInput, formatValue, grantsAccess, hashPassword, humanize, importSigningKey, initialFormValues, isLiveSubscription, issuesByField, kebabCase, matchesContentType, optionLabel, pascalCase, pluralize, randomLetters, relationGraph, renderTransactionalEmail, shouldApplySubscription, signToken, snakeCase, sniffMatches, statusTone, subscriptionPriceId, subscriptionState, toSubscriptionStatus, verifyPassword, verifyToken, words };