@scrawn/core 0.0.3 → 0.0.6

package/dist/core/pricing/serialize.js

@@ -0,0 +1,127 @@
+/**
+ * Pricing DSL Serialization
+ *
+ * This module converts typed pricing expression ASTs into string format
+ * that the backend can parse and evaluate.
+ *
+ * Output format examples:
+ * - Amount: 250
+ * - Tag: tag(PREMIUM_CALL)
+ * - Addition: add(100,tag(FEE),250)
+ * - Complex: add(mul(tag(PREMIUM_CALL),3),tag(EXTRA_FEE),250)
+ *
+ * The format is designed to be:
+ * - Unambiguous (parseable by the backend)
+ * - Human-readable (for debugging)
+ * - Compact (minimal whitespace, no quotes around tag names)
+ */
+/**
+ * Serialize a pricing expression to a string.
+ *
+ * @param expr - The expression to serialize
+ * @returns A string representation that the backend can parse
+ *
+ * @example
+ * ```typescript
+ * const expr = add(mul(tag('PREMIUM'), 3), 100);
+ * const str = serializeExpr(expr);
+ * // "add(mul(tag(PREMIUM),3),100)"
+ * ```
+ */
+export function serializeExpr(expr) {
+    switch (expr.kind) {
+        case "amount":
+            return serializeAmount(expr);
+        case "tag":
+            return serializeTag(expr);
+        case "exprRef":
+            return `expr(${expr.name})`;
+        case "op":
+            return serializeOp(expr);
+        case "inputTokens":
+            throw new Error("Cannot serialize unresolved inputTokens() placeholder. " +
+                "Token placeholders must be resolved before serialization. " +
+                "This is an SDK bug — please report it.");
+        case "outputTokens":
+            throw new Error("Cannot serialize unresolved outputTokens() placeholder. " +
+                "Token placeholders must be resolved before serialization. " +
+                "This is an SDK bug — please report it.");
+    }
+}
+/**
+ * Serialize an amount expression.
+ * Just the integer value.
+ */
+function serializeAmount(expr) {
+    return expr.value.toString();
+}
+/**
+ * Serialize a tag expression.
+ * Format: tag(TAG_NAME)
+ * Tag names are unquoted (validation ensures valid identifier format).
+ */
+function serializeTag(expr) {
+    return `tag(${expr.name})`;
+}
+/**
+ * Serialize an operation expression.
+ * Format: op(arg1,arg2,arg3,...)
+ */
+function serializeOp(expr) {
+    const opName = expr.op.toLowerCase();
+    const args = expr.args.map(serializeExpr).join(",");
+    return `${opName}(${args})`;
+}
+/**
+ * Pretty-print a pricing expression with indentation.
+ * Useful for debugging and logging.
+ *
+ * @param expr - The expression to format
+ * @param indent - Number of spaces for indentation (default 2)
+ * @returns A formatted, multi-line string representation
+ *
+ * @example
+ * ```typescript
+ * const expr = add(mul(tag('PREMIUM'), 3), 100);
+ * console.log(prettyPrintExpr(expr));
+ * // add(
+ * //   mul(
+ * //     tag(PREMIUM),
+ * //     3
+ * //   ),
+ * //   100
+ * // )
+ * ```
+ */
+export function prettyPrintExpr(expr, indent = 2) {
+    return prettyPrintInternal(expr, 0, indent);
+}
+function prettyPrintInternal(expr, level, indent) {
+    const pad = " ".repeat(level * indent);
+    switch (expr.kind) {
+        case "amount":
+            return expr.value.toString();
+        case "tag":
+            return `tag(${expr.name})`;
+        case "exprRef":
+            return `expr(${expr.name})`;
+        case "inputTokens":
+            return "inputTokens()";
+        case "outputTokens":
+            return "outputTokens()";
+        case "op": {
+            const opName = expr.op.toLowerCase();
+            if (expr.args.length === 0) {
+                return `${opName}()`;
+            }
+            const args = expr.args
+                .map((arg) => {
+                const inner = prettyPrintInternal(arg, level + 1, indent);
+                return " ".repeat((level + 1) * indent) + inner;
+            })
+                .join(",\n");
+            return `${opName}(\n${args}\n${pad})`;
+        }
+    }
+}
+//# sourceMappingURL=serialize.js.map

package/dist/core/pricing/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../../src/core/pricing/serialize.ts"],"names":[],"mappings":"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"}

package/dist/core/pricing/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Pricing DSL Types
+ *
+ * This module defines the type-safe AST for pricing expressions.
+ * The SDK builds typed expressions using these types, then serializes
+ * them to strings for the backend to parse and evaluate.
+ *
+ * @example
+ * ```typescript
+ * import { add, mul, tag } from '@scrawn/core';
+ *
+ * // Build a pricing expression: (PREMIUM_CALL * 3) + EXTRA_FEE + 250 cents
+ * const expr = add(mul(tag('PREMIUM_CALL'), 3), tag('EXTRA_FEE'), 250);
+ * ```
+ */
+/**
+ * Supported arithmetic operations for pricing expressions.
+ */
+export type OpType = "ADD" | "SUB" | "MUL" | "DIV";
+/**
+ * Intellisense hint type for tag names.
+ * Tag names must be ALL CAPS with underscores only (e.g., PREMIUM_CALL, FEE, INPUT_RATE).
+ * No lowercase, digits, or hyphens allowed.
+ *
+ * This is a branded type that provides IDE hints while remaining compatible with `string`.
+ */
+export type TagName = Uppercase<string> & {
+    readonly __brand?: "TagName";
+};
+/**
+ * A literal amount in cents (must be an integer).
+ */
+export interface AmountExpr {
+    readonly kind: "amount";
+    readonly value: number;
+}
+/**
+ * A reference to a named price tag (resolved by the backend).
+ * Tag names must be ALL CAPS with underscores only (e.g., PREMIUM_CALL, FEE).
+ *
+ * @typeParam TTag - The specific tag name literal (defaults to `string` for untyped usage)
+ */
+export interface TagExpr<TTag extends string = string> {
+    readonly kind: "tag";
+    readonly name: TTag;
+}
+/**
+ * An arithmetic operation combining multiple expressions.
+ *
+ * @typeParam TTag - The tag name type flowing through the expression tree
+ */
+export interface OpExpr<TTag extends string = string> {
+    readonly kind: "op";
+    readonly op: OpType;
+    readonly args: readonly PriceExpr<TTag>[];
+}
+/**
+ * A placeholder for the inputTokens value from an AI token usage payload.
+ * Only valid in expressions used with aiTokenStreamConsumer.
+ * Resolved SDK-side to an AmountExpr before serialization.
+ */
+export interface InputTokensExpr {
+    readonly kind: "inputTokens";
+}
+/**
+ * A placeholder for the outputTokens value from an AI token usage payload.
+ * Only valid in expressions used with aiTokenStreamConsumer.
+ * Resolved SDK-side to an AmountExpr before serialization.
+ */
+export interface OutputTokensExpr {
+    readonly kind: "outputTokens";
+}
+/**
+ * A reference to a persisted expression stored in the Scrawn backend.
+ * Like tags, persisted expressions have a name and resolve to a value
+ * when evaluated by the backend.
+ *
+ * @example
+ * ```typescript
+ * const expr = biller.expr("MY_EXPR"); // type-safe reference
+ * ```
+ */
+export interface ExprRef {
+    readonly kind: "exprRef";
+    readonly name: string;
+}
+/**
+ * A wrapped pricing expression — the only type accepted by `debitExpr` fields.
+ *
+ * Created exclusively via `biller.expr()`. This wrapper ensures all expressions
+ * flow through a consistent entry point that provides type-safety for both
+ * inline expressions and persisted expression references.
+ *
+ * @typeParam TTag - The tag name type flowing through the expression tree
+ *
+ * @example
+ * ```typescript
+ * // inline expression
+ * const expr = biller.expr(mul(biller.tag("PREMIUM_CALL"), 3));
+ *
+ * // persisted expression reference
+ * const expr = biller.expr("MY_EXPR");
+ * ```
+ */
+export interface ScrawnExpr<TTag extends string = string> {
+    readonly _expr: PriceExpr<TTag> | ExprRef;
+}
+/**
+ * A pricing expression - can be a literal amount, a tag reference, an operation,
+ * a token placeholder (inputTokens/outputTokens), or a persisted expression reference.
+ *
+ * @typeParam TTag - The tag name type flowing through the expression tree
+ */
+export type PriceExpr<TTag extends string = string> = AmountExpr | TagExpr<TTag> | OpExpr<TTag> | InputTokensExpr | OutputTokensExpr | ExprRef;
+/**
+ * Input type for DSL builder functions.
+ * Accepts either a PriceExpr or a raw number (interpreted as cents).
+ *
+ * @typeParam TTag - The tag name type flowing through the expression tree
+ */
+export type ExprInput<TTag extends string = string> = PriceExpr<TTag> | ScrawnExpr<TTag> | number;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/pricing/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/pricing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACnD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAClD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,UAAU,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAC9C,UAAU,GACV,OAAO,CAAC,IAAI,CAAC,GACb,MAAM,CAAC,IAAI,CAAC,GACZ,eAAe,GACf,gBAAgB,GAChB,OAAO,CAAC;AAEZ;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC"}

package/dist/core/pricing/types.js

@@ -0,0 +1,17 @@
+/**
+ * Pricing DSL Types
+ *
+ * This module defines the type-safe AST for pricing expressions.
+ * The SDK builds typed expressions using these types, then serializes
+ * them to strings for the backend to parse and evaluate.
+ *
+ * @example
+ * ```typescript
+ * import { add, mul, tag } from '@scrawn/core';
+ *
+ * // Build a pricing expression: (PREMIUM_CALL * 3) + EXTRA_FEE + 250 cents
+ * const expr = add(mul(tag('PREMIUM_CALL'), 3), tag('EXTRA_FEE'), 250);
+ * ```
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/pricing/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/pricing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/core/pricing/validate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pricing DSL Validation
+ *
+ * This module provides light SDK-side validation for pricing expressions.
+ * The backend performs full validation; the SDK only catches obvious errors
+ * early to provide better developer experience.
+ *
+ * SDK validates:
+ * - Division by literal zero
+ * - Non-integer cents (amounts must be integers)
+ * - Non-finite numbers (NaN, Infinity)
+ * - Empty operation arguments (ops need at least 2 args)
+ * - Empty/whitespace tag names
+ * - Tag name format (must be ALL_CAPS with underscores only)
+ *
+ * SDK does NOT validate:
+ * - Tag existence (backend resolves tags)
+ * - Division by zero when divisor is a tag (backend handles)
+ * - Overflow (backend handles)
+ * - Negative results (backend handles)
+ */
+import type { PriceExpr } from "./types.js";
+/**
+ * Error thrown when a pricing expression fails validation.
+ */
+export declare class PricingExpressionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a pricing expression.
+ * Throws PricingExpressionError if validation fails.
+ *
+ * @param expr - The expression to validate
+ * @throws PricingExpressionError if validation fails
+ */
+export declare function validateExpr(expr: PriceExpr<string>): void;
+/**
+ * Check if an expression is valid without throwing.
+ * Returns true if valid, false otherwise.
+ *
+ * @param expr - The expression to check
+ * @returns true if the expression is valid
+ */
+export declare function isValidExpr(expr: PriceExpr<string>): boolean;
+/**
+ * Check if an expression tree contains any token placeholder nodes
+ * (inputTokens or outputTokens).
+ *
+ * Used to reject token placeholders in contexts where they are not valid
+ * (e.g., SDK call event payloads).
+ *
+ * @param expr - The expression to check
+ * @returns true if the expression contains any token placeholders
+ */
+export declare function containsTokenExpr(expr: PriceExpr<string>): boolean;
+//# sourceMappingURL=validate.d.ts.map

package/dist/core/pricing/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/core/pricing/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAU,MAAM,YAAY,CAAC;AAEpD;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAqB1D;AAqFD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,OAAO,CAO5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,OAAO,CAYlE"}

package/dist/core/pricing/validate.js

@@ -0,0 +1,162 @@
+/**
+ * Pricing DSL Validation
+ *
+ * This module provides light SDK-side validation for pricing expressions.
+ * The backend performs full validation; the SDK only catches obvious errors
+ * early to provide better developer experience.
+ *
+ * SDK validates:
+ * - Division by literal zero
+ * - Non-integer cents (amounts must be integers)
+ * - Non-finite numbers (NaN, Infinity)
+ * - Empty operation arguments (ops need at least 2 args)
+ * - Empty/whitespace tag names
+ * - Tag name format (must be ALL_CAPS with underscores only)
+ *
+ * SDK does NOT validate:
+ * - Tag existence (backend resolves tags)
+ * - Division by zero when divisor is a tag (backend handles)
+ * - Overflow (backend handles)
+ * - Negative results (backend handles)
+ */
+/**
+ * Error thrown when a pricing expression fails validation.
+ */
+export class PricingExpressionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PricingExpressionError";
+    }
+}
+/**
+ * Validate a pricing expression.
+ * Throws PricingExpressionError if validation fails.
+ *
+ * @param expr - The expression to validate
+ * @throws PricingExpressionError if validation fails
+ */
+export function validateExpr(expr) {
+    switch (expr.kind) {
+        case "amount":
+            validateAmount(expr.value);
+            break;
+        case "tag":
+            validateTagName(expr.name);
+            break;
+        case "op":
+            validateOp(expr);
+            break;
+        case "exprRef":
+            validateTagName(expr.name); // same ALL_CAPS format as tags
+            break;
+        case "inputTokens":
+        case "outputTokens":
+            // Token placeholders are valid AST nodes — no validation needed.
+            // Context-level validation (e.g., rejecting them in SDK call payloads)
+            // is handled in event.ts, not here.
+            break;
+    }
+}
+/**
+ * Validate an amount value.
+ * Must be a finite integer.
+ */
+function validateAmount(value) {
+    if (!Number.isFinite(value)) {
+        throw new PricingExpressionError(`Amount must be a finite number, got: ${value}`);
+    }
+    if (!Number.isInteger(value)) {
+        throw new PricingExpressionError(`Amount must be an integer (cents), got: ${value}. ` +
+            `Hint: Use cents instead of dollars (e.g., 250 instead of 2.50)`);
+    }
+}
+/**
+ * Validate a tag name.
+ * Must be ALL CAPS with underscores only (e.g., PREMIUM_CALL, FEE, INPUT_RATE).
+ * No lowercase, digits, or hyphens allowed.
+ */
+function validateTagName(name) {
+    if (typeof name !== "string") {
+        throw new PricingExpressionError(`Tag name must be a string, got: ${typeof name}`);
+    }
+    if (name.length === 0) {
+        throw new PricingExpressionError("Tag name cannot be empty");
+    }
+    if (name.trim() !== name) {
+        throw new PricingExpressionError(`Tag name cannot have leading or trailing whitespace: "${name}"`);
+    }
+    if (name.trim().length === 0) {
+        throw new PricingExpressionError("Tag name cannot be only whitespace");
+    }
+    // Validate tag name format: ALL CAPS with underscores only
+    if (!/^[A-Z_]+$/.test(name)) {
+        throw new PricingExpressionError(`Tag name must be ALL CAPS with underscores only (e.g., PREMIUM_CALL, FEE). ` +
+            `No lowercase, digits, or hyphens allowed. Got: "${name}"`);
+    }
+}
+/**
+ * Validate an operation expression.
+ * Must have at least 2 arguments.
+ * For division, checks for literal zero divisors.
+ */
+function validateOp(expr) {
+    const { op, args } = expr;
+    // Must have at least 2 arguments
+    if (args.length < 2) {
+        throw new PricingExpressionError(`Operation ${op.toLowerCase()} requires at least 2 arguments, got: ${args.length}`);
+    }
+    // Recursively validate all arguments
+    for (const arg of args) {
+        validateExpr(arg);
+    }
+    // Check for division by literal zero
+    if (op === "DIV") {
+        // Check all divisors (all args after the first)
+        for (let i = 1; i < args.length; i++) {
+            const arg = args[i];
+            if (arg.kind === "amount" && arg.value === 0) {
+                throw new PricingExpressionError(`Division by zero: divisor at position ${i + 1} is 0`);
+            }
+        }
+    }
+}
+/**
+ * Check if an expression is valid without throwing.
+ * Returns true if valid, false otherwise.
+ *
+ * @param expr - The expression to check
+ * @returns true if the expression is valid
+ */
+export function isValidExpr(expr) {
+    try {
+        validateExpr(expr);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if an expression tree contains any token placeholder nodes
+ * (inputTokens or outputTokens).
+ *
+ * Used to reject token placeholders in contexts where they are not valid
+ * (e.g., SDK call event payloads).
+ *
+ * @param expr - The expression to check
+ * @returns true if the expression contains any token placeholders
+ */
+export function containsTokenExpr(expr) {
+    switch (expr.kind) {
+        case "inputTokens":
+        case "outputTokens":
+            return true;
+        case "op":
+            return expr.args.some(containsTokenExpr);
+        case "amount":
+        case "tag":
+        case "exprRef":
+            return false;
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/core/pricing/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/core/pricing/validate.ts"],"names":[],"mappings":"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"}