@scrawn/core 0.0.2 → 0.0.6

package/dist/core/scrawn.d.ts

@@ -1,24 +1,32 @@
-import type { EventPayload, MiddlewareRequest, MiddlewareResponse, MiddlewareNext, MiddlewareEventConfig } from './types/event.js';
-import type { AllCredentials } from './types/auth.js';
+import type { EventPayload, MiddlewareRequest, MiddlewareResponse, MiddlewareNext, MiddlewareEventConfig, AITokenUsagePayload, EventConsumerErrorCallback } from "./types/event.js";
+import type { AllCredentials } from "./types/auth.js";
+import type { TagExpr, PriceExpr, ScrawnExpr } from "./pricing/types.js";
+import { GrpcClient } from "./grpc/index.js";
+import type { StreamEventResponse } from "../gen/event/v1/event_pb.js";
 /**
  * Main SDK class for Scrawn billing infrastructure.
  *
  * Manages authentication, event tracking, and credential caching.
  * All event consumption methods are available directly on the SDK instance.
  *
+ * @typeParam TTags - Union of valid tag names for compile-time type checking
+ *
  * @example
  * ```typescript
- * import { Scrawn } from '@scrawn/core';
+ * import { createScrawn } from '@scrawn/core';
  *
- * // Initialize SDK
- * const scrawn = new Scrawn({ apiKey: process.env.SCRAWN_KEY });
- * await scrawn.init();
+ * const biller = createScrawn({
+ *   apiKey: process.env.SCRAWN_KEY,
+ *   baseURL: 'http://localhost:8069',
+ *   tags: ["PREMIUM_CALL", "EXTRA_FEE"] as const,
+ * });
  *
- * // Track SDK calls
- * await scrawn.sdkCallEventConsumer({ userId: 'u123', debitAmount: 3 });
+ * // Tags are compile-time checked
+ * biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'PREMIUM_FEATURE' });
+ * // biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'UNKNOWN' }); // Type error!
  * ```
  */
-export declare class Scrawn {
+export declare class Scrawn<TTags extends string = string, TExprs extends string = string> {
     /** Map of authentication method names to their implementations */
     private authMethods;
     /**
@@ -30,6 +38,12 @@ export declare class Scrawn {
     private apiKey;
     /** gRPC client for making type-safe API calls */
     private grpcClient;
+    /** Public access to the gRPC client for use by other packages (e.g. @scrawn/analytics) */
+    get grpc(): GrpcClient;
+    /** API key used for authorizing gRPC calls */
+    get apikey(): string;
+    private notifyEventConsumerError;
+    private notifyValidationError;
     /**
      * Creates a new Scrawn SDK instance.
      *
@@ -47,9 +61,58 @@ export declare class Scrawn {
      * ```
      */
     constructor(config: {
-        apiKey: AllCredentials['apiKey'];
+        apiKey: AllCredentials["apiKey"];
         baseURL: string;
+        secure?: boolean;
+        credentials?: import("@grpc/grpc-js").ChannelCredentials;
     });
+    private parseURLToTarget;
+    /**
+     * Create a type-safe tag reference.
+     *
+     * Only tag names known to this biller instance are accepted at compile time.
+     * Tag values are resolved to cent amounts by the backend at runtime.
+     *
+     * @param name - The tag name (must be one of the known tags for this instance)
+     * @returns A TagExpr referencing the named tag
+     * @throws PricingExpressionError at runtime if name format is invalid
+     *
+     * @example
+     * ```typescript
+     * const expr = mul(biller.tag("PREMIUM_CALL"), 3);
+     * ```
+     */
+    tag<T extends TTags>(name: T): TagExpr<T>;
+    /**
+     * Create a type-safe reference to a persisted expression.
+     *
+     * Expression names are compile-time checked against known expressions
+     * synced from the Scrawn server. The backend resolves the stored
+     * expression string and evaluates it at runtime.
+     *
+     * Also accepts inline PriceExpr as a passthrough for a consistent
+     * `biller.expr()` entry point for all expressions.
+     *
+     * @param nameOrExpr - The persisted expression name or an inline PriceExpr
+     * @returns An ExprRef (if name) or the original PriceExpr (passthrough)
+     *
+     * @example
+     * ```typescript
+     * // Reference a persisted expression
+     * biller.sdkCallEventConsumer({
+     *   userId: 'u123',
+     *   debitExpr: biller.expr("MY_EXPR"),
+     * });
+     *
+     * // Inline expression passthrough
+     * biller.sdkCallEventConsumer({
+     *   userId: 'u123',
+     *   debitExpr: biller.expr(mul(biller.tag("PREMIUM_CALL"), 3)),
+     * });
+     * ```
+     */
+    expr<T extends TExprs>(name: T): ScrawnExpr<TTags>;
+    expr(expr: PriceExpr<TTags>): ScrawnExpr<TTags>;
     /**
      * Register an authentication method with the SDK.
      *
@@ -91,24 +154,44 @@ export declare class Scrawn {
      *
      * @param payload - The SDK call data to track
      * @param payload.userId - Unique identifier of the user making the call
-     * @param payload.debitAmount - Amount to debit from the user's account
-     * @returns A promise that resolves when the event is tracked
-     * @throws Error if payload validation fails
+     * @param payload.debitAmount - (Optional) Direct amount in cents to debit from the user's account
+     * @param payload.debitTag - (Optional) Named price tag for backend-managed pricing
+     * @param payload.debitExpr - (Optional) Pricing expression for complex calculations
+     * @param options - Optional configuration
+     * @param options.onError - Optional callback for handling validation or gRPC errors
+     * @returns A promise that resolves when the event is tracked or returns early on error
      *
      * @example
      * ```typescript
+     * import { add, mul, tag } from '@scrawn/core';
+     *
+     * // Using direct amount (500 cents = $5.00)
+     * await scrawn.sdkCallEventConsumer({
+     *   userId: 'user_abc123',
+     *   debitAmount: 500
+     * });
+     *
+     * // Using price tag
+     * await scrawn.sdkCallEventConsumer({
+     *   userId: 'user_abc123',
+     *   debitTag: 'PREMIUM_FEATURE'
+     * });
+     *
+     * // Using pricing expression: (PREMIUM_CALL * 3) + EXTRA_FEE + 250 cents
      * await scrawn.sdkCallEventConsumer({
      *   userId: 'user_abc123',
-     *   debitAmount: 10
+     *   debitExpr: add(mul(tag('PREMIUM_CALL'), 3), tag('EXTRA_FEE'), 250)
      * });
      * ```
      */
-    sdkCallEventConsumer(payload: EventPayload): Promise<void>;
+    sdkCallEventConsumer(payload: EventPayload<TTags>, options?: {
+        onError?: EventConsumerErrorCallback;
+    }): Promise<void>;
     /**
      * Create an Express-compatible middleware for tracking API endpoint usage.
      *
      * This middleware automatically tracks requests to your API endpoints for billing purposes.
-     * You provide an extractor function that determines the userId and debitAmount from each request.
+     * You provide an extractor function that determines the userId and debit info (amount or tag) from each request.
      * Optionally, you can provide a whitelist array to only track specific endpoints,
      * or a blacklist array to exclude specific endpoints from tracking.
      *
@@ -124,6 +207,7 @@ export declare class Scrawn {
      *                            Takes precedence over blacklist. If omitted, all requests will be tracked.
      * @param config.blacklist - Optional array of endpoint patterns to exclude. Same wildcard support as whitelist.
      *                            Only applies to endpoints not in the whitelist.
+     * @param config.onError - Optional callback for handling validation or gRPC errors
      *
      * @returns Express-compatible middleware function
      *
@@ -156,7 +240,7 @@ export declare class Scrawn {
      * }));
      * ```
      */
-    middlewareEventConsumer(config: MiddlewareEventConfig): (req: MiddlewareRequest, res: MiddlewareResponse, next: MiddlewareNext) => Promise<void>;
+    middlewareEventConsumer(config: MiddlewareEventConfig<TTags>): (req: MiddlewareRequest, res: MiddlewareResponse, next: MiddlewareNext) => Promise<void>;
     /**
      * Collect payment by creating a checkout link for a user.
      *
@@ -193,5 +277,122 @@ export declare class Scrawn {
      * @internal
      */
     private consumeEvent;
+    /**
+     * Configuration options for aiTokenStreamConsumer.
+     */
+    /**
+     * Stream AI token usage events to the Scrawn backend (fire-and-forget mode).
+     *
+     * Consumes an async iterable of AI token usage payloads and streams them
+     * to the backend for billing tracking. This is designed for real-time
+     * AI token tracking where usage is reported as tokens are consumed.
+     *
+     * @param stream - An async iterable of AI token usage payloads
+     * @returns A promise that resolves to the stream response or undefined on error
+     */
+    aiTokenStreamConsumer(stream: AsyncIterable<AITokenUsagePayload<TTags>>): Promise<StreamEventResponse | undefined>;
+    /**
+     * Stream AI token usage events to the Scrawn backend (fire-and-forget mode).
+     *
+     * @param stream - An async iterable of AI token usage payloads
+     * @param config - Configuration with return: false (or omitted)
+     * @returns A promise that resolves to the stream response or undefined on error
+     */
+    aiTokenStreamConsumer(stream: AsyncIterable<AITokenUsagePayload<TTags>>, config: {
+        return?: false;
+        onError?: EventConsumerErrorCallback;
+    }): Promise<StreamEventResponse | undefined>;
+    /**
+     * Stream AI token usage events to the Scrawn backend while returning a forked stream.
+     *
+     * When `return: true`, the input stream is forked: one fork is sent to the billing
+     * backend (non-blocking), and the other fork is returned to the caller for streaming
+     * to the user. This enables simultaneous billing and user-facing token streaming.
+     *
+     * @param stream - An async iterable of AI token usage payloads
+     * @param config - Configuration with return: true
+     * @returns Object containing the response promise (or undefined on error) and a forked stream for user consumption
+     *
+     * @example
+     * ```typescript
+     * const { response, stream: userStream } = await scrawn.aiTokenStreamConsumer(
+     *   tokenGenerator(),
+     *   { return: true }
+     * );
+     *
+     * // Stream tokens to user while billing happens in background
+     * for await (const token of userStream) {
+     *   process.stdout.write(token.outputTokens.toString());
+     * }
+     *
+      * // Billing completes after stream is consumed
+      * const result = await response;
+      * if (result) {
+      *   console.log(`Billed ${result.getEventsprocessed()} events`);
+      * }
+     * ```
+     */
+    aiTokenStreamConsumer(stream: AsyncIterable<AITokenUsagePayload<TTags>>, config: {
+        return: true;
+        onError?: EventConsumerErrorCallback;
+    }): Promise<{
+        response: Promise<StreamEventResponse | undefined>;
+        stream: AsyncIterable<AITokenUsagePayload<TTags>>;
+    }>;
+    /**
+     * Transform user-provided AI token usage payloads into StreamEventRequest format.
+     *
+     * Validates each payload and maps it to the gRPC request format.
+     * Invalid payloads are logged and skipped.
+     *
+     * @param stream - The user's async iterable of AITokenUsagePayload
+     * @returns An async iterable of StreamEventRequest payloads
+     * @internal
+     */
+    private transformAITokenStream;
 }
+/**
+ * Configuration for creating a Scrawn instance via {@link createScrawn}.
+ */
+export interface ScrawnInitConfig {
+    apiKey: string;
+    baseURL: string;
+    secure?: boolean;
+    credentials?: import("@grpc/grpc-js").ChannelCredentials;
+    tags?: readonly string[];
+    expressions?: readonly string[];
+}
+/**
+ * Create a type-safe Scrawn billing instance.
+ *
+ * When `tags` or `expressions` are provided as const arrays, the returned
+ * instance is parameterized with the union of those names. All pricing
+ * methods will be compile-time checked against the known set.
+ *
+ * @example
+ * ```typescript
+ * import { createScrawn, mul, inputTokens } from '@scrawn/core';
+ *
+ * const biller = createScrawn({
+ *   apiKey: process.env.SCRAWN_KEY,
+ *   baseURL: process.env.SCRAWN_BASE_URL,
+ *   tags: ["PREMIUM_CALL", "EXTRA_FEE"] as const,
+ *   expressions: ["MY_EXPR"] as const,
+ * });
+ *
+ * biller.sdkCallEventConsumer({
+ *   userId: 'u123',
+ *   debitExpr: biller.expr("MY_EXPR"),          // persisted expression
+ * });
+ * biller.sdkCallEventConsumer({
+ *   userId: 'u123',
+ *   debitExpr: mul(biller.tag("PREMIUM_CALL"), 3), // inline
+ * });
+ * ```
+ */
+export declare function createScrawn<const TTags extends readonly string[], const TExprs extends readonly string[]>(config: ScrawnInitConfig & {
+    tags: TTags;
+    expressions: TExprs;
+}): Scrawn<TTags[number], TExprs[number]>;
+export declare function createScrawn(config: ScrawnInitConfig): Scrawn;
 //# sourceMappingURL=scrawn.d.ts.map

package/dist/core/scrawn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrawn.d.ts","sourceRoot":"","sources":["../../src/core/scrawn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAgC,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAYpF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IACjB,kEAAkE;IAClE,OAAO,CAAC,WAAW,CAAuD;IAE1E;;;OAGG;IACH,OAAO,CAAC,SAAS,CAA6C;IAE9D,8CAA8C;IAC9C,OAAO,CAAC,MAAM,CAA2B;IAEzC,iDAAiD;IACjD,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;;;;;;;;;;;OAeG;gBACS,MAAM,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAWzE;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;;;;;;;;;;OAgBG;YACW,WAAW;IAmBzB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,uBAAuB,CAAC,MAAM,EAAE,qBAAqB,IACrC,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc;IAkDrF;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BrD;;;;;;;;;;;;;;;;OAgBG;YACW,YAAY;CA8C3B"}
+{"version":3,"file":"scrawn.d.ts","sourceRoot":"","sources":["../../src/core/scrawn.ts"],"names":[],"mappings":"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"}