@flintpay/node 0.2.0-beta.1

package/package.json

@@ -0,0 +1,45 @@
+{
+  "dependencies": {
+    "@types/node": "22.20.1"
+  },
+  "description": "Flint Public API server SDK",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    },
+    "./custom/*": "./custom/*"
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md",
+    "REFERENCE.md",
+    "LICENSE",
+    "examples/",
+    "guides/",
+    "custom/"
+  ],
+  "license": "Apache-2.0",
+  "main": "./index.js",
+  "name": "@flintpay/node",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "types": "./index.d.ts",
+  "version": "0.2.0-beta.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flint-pay/flint-sdks.git",
+    "directory": "node"
+  },
+  "homepage": "https://developers.withflintpay.com",
+  "bugs": {
+    "url": "https://github.com/flint-pay/flint-sdks/issues"
+  }
+}

package/runtime-plan.d.ts

@@ -0,0 +1,50 @@
+import type { Operation, Schema, Auth, Webhook, Config, IncomingWebhook, AuthenticationMode } from './contract.js';
+import { CODEC_FORMAT, type CodecPlan } from './codec-plan.js';
+/** Declared success statuses; default remains a runtime fallback, never an implicit redirect. */
+export declare function successStatus(status: string): boolean;
+export interface RuntimeContract {
+    userAgent?: string;
+    validation?: Config['validation'];
+    operations: Operation[];
+    incoming?: IncomingWebhook[];
+    definitions?: Record<string, Schema>;
+    auth?: Auth;
+    authentication?: Record<string, AuthenticationMode>;
+    apiVersion?: {
+        header: string;
+        value: string;
+    };
+    webhook?: Webhook;
+    money?: {
+        currencies: Record<string, number>;
+    };
+    errors?: Config['errors'];
+}
+export interface CompiledOperation extends Omit<Operation, 'parameters' | 'body' | 'responses' | 'streamEventSchemas'> {
+    streamEventCodecs?: Record<string, CodecPlan>;
+    parameters: (Omit<Operation['parameters'][number], 'schema'> & {
+        codec: CodecPlan;
+    })[];
+    body?: CodecPlan;
+    responses: Record<string, Omit<Operation['responses'][string], 'schema'> & {
+        codec?: CodecPlan;
+        model?: string;
+        variants?: Record<string, string>;
+    }>;
+}
+export interface CompiledRuntimePlan extends Omit<RuntimeContract, 'operations' | 'definitions' | 'webhook' | 'incoming'> {
+    format: typeof CODEC_FORMAT;
+    semantics: string;
+    operations: CompiledOperation[];
+    incoming?: (Omit<IncomingWebhook, 'schema'> & {
+        codec: CodecPlan;
+    })[];
+    definitions?: Record<string, CodecPlan>;
+    webhook?: Omit<Webhook, 'events'> & {
+        events: Record<string, CodecPlan>;
+        eventModels?: Record<string, string>;
+    };
+}
+/** Provider policy is resolved here; transports receive only explicit operation descriptors. */
+export declare function compileRuntimePlan(contract: RuntimeContract): CompiledRuntimePlan;
+export declare function assertRuntimePlan(value: unknown): asserts value is CompiledRuntimePlan;

package/runtime-plan.js

@@ -0,0 +1,187 @@
+import { compileCodec, assertCodecPlan, CODEC_FORMAT, CODEC_SEMANTICS, } from './codec-plan.js';
+/** Declared success statuses; default remains a runtime fallback, never an implicit redirect. */
+export function successStatus(status) {
+    return /^2\d\d$/.test(status) || ['302', '307', '304'].includes(status);
+}
+/** Provider policy is resolved here; transports receive only explicit operation descriptors. */
+export function compileRuntimePlan(contract) {
+    const root = (schema) => ({
+        ...compileCodec(schema),
+        constraints: contract.validation !== 'encoding',
+    });
+    const { operations, definitions, webhook, incoming, ...settings } = contract;
+    return {
+        ...settings,
+        format: CODEC_FORMAT,
+        semantics: CODEC_SEMANTICS,
+        ...(incoming
+            ? {
+                incoming: incoming.map(({ schema, ...declaration }) => ({
+                    ...declaration,
+                    codec: root(schema),
+                })),
+            }
+            : {}),
+        operations: operations.map((op) => {
+            const { parameters, body, responses, streamEventSchemas, ...operation } = op;
+            return {
+                ...operation,
+                ...(streamEventSchemas
+                    ? {
+                        streamEventCodecs: Object.fromEntries(Object.entries(streamEventSchemas).map(([name, schema]) => [name, root(schema)])),
+                    }
+                    : {}),
+                parameters: parameters.map(({ schema, ...parameter }) => ({
+                    ...parameter,
+                    codec: root(schema),
+                })),
+                ...(body ? { body: root(body) } : {}),
+                responses: Object.fromEntries(Object.entries(responses).map(([status, { schema, ...response }]) => [
+                    status,
+                    {
+                        ...response,
+                        bodyKind: response.bodyKind ?? (schema ? 'json' : 'empty'),
+                        classification: response.classification ??
+                            (successStatus(status)
+                                ? ['302', '307'].includes(status)
+                                    ? 'redirect'
+                                    : 'success'
+                                : 'error'),
+                        ...(schema ? { codec: root(schema) } : {}),
+                    },
+                ])),
+            };
+        }),
+        ...(definitions
+            ? {
+                definitions: Object.fromEntries(Object.entries(definitions).map(([name, schema]) => [name, compileCodec(schema)])),
+            }
+            : {}),
+        ...(webhook
+            ? {
+                webhook: {
+                    ...webhook,
+                    events: Object.fromEntries(Object.entries(webhook.events).map(([name, schema]) => [name, root(schema)])),
+                },
+            }
+            : {}),
+    };
+}
+export function assertRuntimePlan(value) {
+    function record(value, path) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(path + ': invalid compiled runtime record');
+        return value;
+    }
+    const plan = record(value, 'runtime');
+    if (plan.format !== CODEC_FORMAT || typeof plan.semantics !== 'string')
+        throw new Error('Unsupported compiled runtime format');
+    if (!Array.isArray(plan.operations))
+        throw new Error('Missing compiled operations');
+    if (plan.authentication !== undefined)
+        for (const [name, value] of Object.entries(record(plan.authentication, 'authentication'))) {
+            const mode = record(value, 'authentication.' + name);
+            if (!Array.isArray(mode.schemes) || !mode.schemes.length)
+                throw new Error('Invalid authentication mode');
+            const destinations = new Set();
+            for (const item of mode.schemes) {
+                const scheme = record(item, 'authentication scheme');
+                if (typeof scheme.name !== 'string' ||
+                    typeof scheme.header !== 'string' ||
+                    !['bearer', 'apiKey'].includes(String(scheme.type)) ||
+                    !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(scheme.header))
+                    throw new Error('Invalid authentication scheme');
+                if (destinations.has(scheme.header.toLowerCase()))
+                    throw new Error('Conflicting authentication destinations');
+                destinations.add(scheme.header.toLowerCase());
+            }
+        }
+    if (plan.incoming !== undefined) {
+        if (!Array.isArray(plan.incoming))
+            throw new Error('Invalid incoming contracts');
+        for (const declaration of plan.incoming) {
+            const entry = record(declaration, 'incoming');
+            for (const key of ['name', 'method', 'pointer', 'model'])
+                if (typeof entry[key] !== 'string')
+                    throw new Error('Invalid incoming ' + key);
+            if (entry.schema !== undefined)
+                throw new Error('Raw schema in incoming contract');
+            assertCodecPlan(entry.codec, 'incoming.' + entry.name);
+        }
+    }
+    for (const [index, value] of plan.operations.entries()) {
+        const op = record(value, `operations[${index}]`);
+        if (op.authModes !== undefined &&
+            (!Array.isArray(op.authModes) ||
+                !op.authModes.every((name) => typeof name === 'string' &&
+                    plan.authentication &&
+                    Object.hasOwn(plan.authentication, name))))
+            throw new Error('Invalid operation authentication modes');
+        if (typeof op.id !== 'string' ||
+            typeof op.path !== 'string' ||
+            typeof op.verb !== 'string' ||
+            !Array.isArray(op.parameters))
+            throw new Error('Invalid compiled operation');
+        for (const parameter of op.parameters) {
+            const field = record(parameter, `${op.id}.parameter`);
+            if (typeof field.name !== 'string' ||
+                !['path', 'query', 'header'].includes(String(field.in)) ||
+                field.schema !== undefined)
+                throw new Error(`${op.id}: invalid compiled parameter`);
+            assertCodecPlan(field.codec, `${op.id}.parameter.${field.name}`);
+        }
+        if (op.body !== undefined)
+            assertCodecPlan(op.body, `${op.id}.body`);
+        if (op.streamEventSchemas !== undefined)
+            throw new Error('Raw stream schemas in compiled operation');
+        if (op.streamEventCodecs !== undefined)
+            for (const [event, codec] of Object.entries(record(op.streamEventCodecs, `${op.id}.streamEventCodecs`)))
+                assertCodecPlan(codec, `${op.id}.streamEventCodecs.${event}`);
+        if (op.stream !== undefined) {
+            const stream = record(op.stream, `${op.id}.stream`);
+            for (const key of ['idleTimeoutMs', 'maxEventBytes'])
+                if (stream[key] !== undefined &&
+                    (!Number.isSafeInteger(stream[key]) || Number(stream[key]) <= 0))
+                    throw new Error('Invalid stream limits');
+        }
+        for (const [status, response] of Object.entries(record(op.responses, `${op.id}.responses`))) {
+            const result = record(response, `${op.id}.responses.${status}`);
+            if (result.bodyKind !== undefined &&
+                !['empty', 'json', 'binary', 'sse'].includes(String(result.bodyKind)))
+                throw new Error('Unsupported response body kind');
+            if (result.classification !== undefined &&
+                !['success', 'error', 'redirect'].includes(String(result.classification)))
+                throw new Error('Unsupported response classification');
+            if (result.classification === 'redirect' && !['302', '307'].includes(status))
+                throw new Error('Invalid redirect status');
+            if (result.locationRequired !== undefined && typeof result.locationRequired !== 'boolean')
+                throw new Error('Invalid Location requirement');
+            if (result.bodyKind === 'json' && result.codec === undefined)
+                throw new Error('Missing JSON response codec');
+            if (result.bodyKind === 'sse' &&
+                (result.codec !== undefined || result.mediaType !== 'text/event-stream'))
+                throw new Error('Invalid SSE response descriptor');
+            if (result.bodyKind === 'binary' &&
+                (result.codec !== undefined || result.mediaType !== 'application/pdf'))
+                throw new Error('Invalid binary response descriptor');
+            if (result.codec !== undefined)
+                assertCodecPlan(result.codec, `${op.id}.responses.${status}`);
+            if (result.schema !== undefined)
+                throw new Error('Raw schema in compiled response');
+            for (const key of ['model', 'mediaType'])
+                if (result[key] !== undefined && typeof result[key] !== 'string')
+                    throw new Error(`${op.id}.responses.${status}: invalid ${key}`);
+            if (result.variants !== undefined)
+                for (const binding of Object.values(record(result.variants, `${op.id}.responses.${status}.variants`)))
+                    if (typeof binding !== 'string')
+                        throw new Error(`${op.id}.responses.${status}: invalid variant binding`);
+        }
+    }
+    if (plan.definitions !== undefined)
+        for (const [name, codec] of Object.entries(record(plan.definitions, 'definitions')))
+            assertCodecPlan(codec, 'definitions.' + name);
+    if (plan.webhook !== undefined)
+        for (const [name, codec] of Object.entries(record(record(plan.webhook, 'webhook').events, 'webhook.events')))
+            assertCodecPlan(codec, 'webhook.events.' + name);
+}
+//# sourceMappingURL=runtime-plan.js.map

package/runtime.d.ts

@@ -0,0 +1,192 @@
+import { inspect } from 'node:util';
+import type { Schema } from './contract.js';
+import { type RuntimeContract, type CompiledRuntimePlan } from './runtime-plan.js';
+export type { RuntimeContract } from './runtime-plan.js';
+export type { Operation, Schema } from './contract.js';
+import { type CodecPlan } from './codec-plan.js';
+export { directionalSchema } from './codec-plan.js';
+export type ErrorKind = 'transport' | 'authentication' | 'validation' | 'rate_limit' | 'api' | 'conflict' | 'protocol' | 'cancelled' | 'deadline' | 'destination';
+export interface Metadata {
+    status: number;
+    headers: Record<string, string>;
+    requestId?: string;
+    attempts: number;
+    durationMs: number;
+    url?: string;
+}
+export interface Result<T> {
+    data: T;
+    meta: Metadata;
+    raw: T extends Uint8Array ? Uint8Array : string;
+}
+export declare class SdkError extends Error {
+    kind: ErrorKind;
+    outcome: 'unknown' | 'response' | 'not_sent';
+    retryAllowed: boolean;
+    meta?: Metadata | undefined;
+    code?: string | undefined;
+    details?: unknown | undefined;
+    raw?: string | undefined;
+    constructor(kind: ErrorKind, message: string, outcome?: 'unknown' | 'response' | 'not_sent', retryAllowed?: boolean, meta?: Metadata | undefined, code?: string | undefined, details?: unknown | undefined, options?: ErrorOptions, raw?: string | undefined);
+    [inspect.custom](): {
+        name: string;
+        kind: ErrorKind;
+        message: string;
+        outcome: "response" | "unknown" | "not_sent";
+        retryAllowed: boolean;
+        requestId: string | undefined;
+        status: number | undefined;
+    };
+}
+export interface DiagnosticEvent {
+    operation: string;
+    attempt: number;
+    status?: number;
+    requestId?: string;
+    durationMs: number;
+    errorKind?: ErrorKind;
+}
+export interface RequestOptions {
+    streamIdleTimeoutMs?: number;
+    streamLifetimeMs?: number;
+    authMode?: string;
+    credentials?: Record<string, string>;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+    ifMatch?: string;
+    timeoutMs?: number;
+    deadlineMs?: number;
+    maxAttempts?: number;
+    signal?: AbortSignal;
+    maxPages?: number;
+    maxItems?: number;
+}
+export interface ClientOptions {
+    baseUrl: string;
+    token?: string;
+    authMode?: string;
+    credentials?: Record<string, Record<string, string>>;
+    allowedOrigins?: string[];
+    allowInsecureHttp?: boolean;
+    timeoutMs?: number;
+    deadlineMs?: number;
+    maxAttempts?: number;
+    transport?: typeof fetch;
+    diagnostics?: (event: DiagnosticEvent) => void;
+    redactFields?: string[];
+}
+export interface ServerSentEvent {
+    event: string;
+    id: string;
+    data: unknown;
+    rawData: string;
+    retry?: number;
+}
+/** A single-consumer stream. Breaking iteration releases the response connection. */
+export declare class EventStream implements AsyncIterable<ServerSentEvent> {
+    private readonly reader;
+    readonly meta: Metadata;
+    private readonly settings;
+    private readonly decodeEvent;
+    private readonly released;
+    private closed;
+    private started;
+    private failure;
+    private lifetime;
+    private readonly abort;
+    constructor(reader: ReadableStreamDefaultReader<Uint8Array>, meta: Metadata, settings: {
+        idleTimeoutMs: number;
+        maxEventBytes: number;
+        lifetimeMs?: number;
+        signal?: AbortSignal;
+    }, decodeEvent?: (event: string, data: string) => unknown, released?: () => void);
+    close(): Promise<void>;
+    [inspect.custom](): {
+        meta: {
+            status: number;
+            requestId: string | undefined;
+            attempts: number;
+            durationMs: number;
+        };
+        closed: boolean;
+    };
+    [Symbol.asyncIterator](): AsyncGenerator<ServerSentEvent>;
+}
+declare class ParsedNumber {
+    readonly value: string;
+    constructor(value: string);
+}
+/** An explicit JSON number for inputs whose schema also permits JSON strings. */
+export declare class ExactNumber extends ParsedNumber {
+    constructor(value: string);
+}
+/** Parse JSON without rounding integers or decimal tokens. Unknown numeric tokens remain exact strings. */
+export declare function parseExact(text: string): unknown;
+export declare function normalize(value: unknown, s: Schema, path?: string, response?: boolean, redactFields?: string[], matching?: boolean, definitions?: Record<string, Schema>, depth?: number, validateConstraints?: boolean, allowUnknownResponseFields?: boolean): any;
+type CodecMode = {
+    mode: 'request' | 'response';
+    direction?: never;
+} | {
+    mode: 'match';
+    direction: 'request' | 'response';
+};
+export type CodecContext = CodecMode & {
+    path?: string;
+    redactFields?: string[];
+    definitions?: Readonly<Record<string, CodecPlan>>;
+    depth?: number;
+    validateConstraints?: boolean;
+    allowUnknownResponseFields?: boolean;
+};
+/** Internal descriptor entry point. Raw schemas are accepted only by the adapter above. */
+export declare function executeCodec(value: unknown, s: CodecPlan, context: CodecContext): unknown;
+export declare function serialize(value: unknown, schema: Schema): string;
+export declare function isKnownVariant(value: unknown, schema: Schema): boolean;
+export declare function isKnownCodec(value: unknown, codec: CodecPlan): boolean;
+export declare function redact(value: unknown, schema?: Schema, fields?: string[], definitions?: Record<string, Schema>, depth?: number): unknown;
+export declare function redactCodec(value: unknown, schema?: CodecPlan, fields?: string[], definitions?: Readonly<Record<string, CodecPlan>>, depth?: number): unknown;
+/** Plain inputs and validated model factories may be composed at any depth. */
+export type InputValue<T> = T | Model<T> | (T extends readonly (infer Item)[] ? InputValue<Item>[] : T extends object ? {
+    [Key in keyof T]: InputValue<T[Key]>;
+} : never);
+export declare class Model<T = unknown> {
+    private readonly value;
+    private readonly codec;
+    private readonly dynamicSchema;
+    constructor(value: InputValue<T>, schema: Schema);
+    toJSON(): T;
+    [inspect.custom](): unknown;
+}
+/** Internal factory; does not expand the public Model class method surface. */
+export declare function modelFromCodec<T>(value: InputValue<T>, codec: CodecPlan): Model<T>;
+export declare class Runtime {
+    private readonly streams;
+    close(): Promise<void>;
+    private readonly options;
+    private readonly base;
+    private readonly allowed;
+    private readonly compiledContract;
+    private readonly dynamicContract;
+    private get contract();
+    constructor(contract: RuntimeContract, options: ClientOptions);
+    [inspect.custom](): {
+        baseUrl: string;
+        credentials: string;
+    };
+    private decode;
+    private checkUrl;
+    request<T = unknown>(id: string, input?: Record<string, unknown>, options?: RequestOptions, continuation?: string): Promise<Result<T>>;
+    pages<T = unknown>(id: string, input?: Record<string, unknown>, options?: RequestOptions): AsyncGenerator<Result<T>>;
+    items<T = unknown>(id: string, input?: Record<string, unknown>, options?: RequestOptions): AsyncGenerator<T>;
+    wait<T = unknown>(id: string, input: Record<string, unknown>, options?: RequestOptions): Promise<Result<T>>;
+    verifyWebhook(rawBody: Uint8Array, headers: Record<string, string>, secrets: string[], nowSeconds?: number): {
+        event: unknown;
+        known: boolean;
+    };
+    money(currency: string, major: string): {
+        currency: string;
+        amount: string;
+    };
+}
+/** Internal factory for generated clients; public Runtime construction remains schema-based. */
+export declare function runtimeFromPlan(contract: CompiledRuntimePlan, options: ClientOptions): Runtime;