@scrawn/core 0.0.3 → 0.0.6

package/dist/core/scrawn.d.ts

@@ -0,0 +1,398 @@
+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 { createScrawn } from '@scrawn/core';
+ *
+ * const biller = createScrawn({
+ *   apiKey: process.env.SCRAWN_KEY,
+ *   baseURL: 'http://localhost:8069',
+ *   tags: ["PREMIUM_CALL", "EXTRA_FEE"] as const,
+ * });
+ *
+ * // Tags are compile-time checked
+ * biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'PREMIUM_FEATURE' });
+ * // biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'UNKNOWN' }); // Type error!
+ * ```
+ */
+export declare class Scrawn<TTags extends string = string, TExprs extends string = string> {
+    /** Map of authentication method names to their implementations */
+    private authMethods;
+    /**
+     * Cache of credentials keyed by auth method name for performance.
+     * Keys are restricted to registered auth method names only.
+     */
+    private credCache;
+    /** API key used for default authentication */
+    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.
+     *
+     * @param config - Configuration object
+     * @param config.apiKey - Your Scrawn API key for authentication
+     * @param config.baseURL - Base URL for the Scrawn API (e.g., 'https://api.scrawn.dev')
+     *
+     * @example
+     * ```typescript
+     * const scrawn = new Scrawn({
+     *   apiKey: 'sk_test_...',
+     *   baseURL: 'https://api.scrawn.dev'
+     * });
+     * await scrawn.init();
+     * ```
+     */
+    constructor(config: {
+        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.
+     *
+     * Auth methods handle credential management and can be shared across multiple event types.
+     * Only auth method names defined in AuthRegistry are allowed.
+     *
+     * @param name - Unique identifier for this auth method (must be in AuthRegistry)
+     * @param auth - Instance of an AuthBase implementation
+     *
+     * @example
+     * ```typescript
+     * scrawn.registerAuthMethod('api', new ApiKeyAuth('sk_test_...'));
+     * ```
+     */
+    private registerAuthMethod;
+    /**
+     * Get credentials for a specific authentication method.
+     *
+     * Credentials are cached after the first fetch for performance.
+     * Subsequent calls return the cached value without re-fetching.
+     * Only auth method names defined in AuthRegistry are allowed.
+     *
+     * @param authMethodName - Name of the auth method to get credentials for (must be in AuthRegistry)
+     * @returns A promise that resolves to the credentials object
+     * @throws Error if the auth method is not registered
+     *
+     * @example
+     * ```typescript
+     * const creds = await scrawn.getCredsFor('api');
+     * // { apiKey: 'sk_test_...' }
+     * ```
+     */
+    private getCredsFor;
+    /**
+     * Track an SDK call event.
+     *
+     * Records SDK usage to the Scrawn backend for billing tracking.
+     * The event is authenticated using the API key provided during SDK initialization.
+     *
+     * @param payload - The SDK call data to track
+     * @param payload.userId - Unique identifier of the user making the call
+     * @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',
+     *   debitExpr: add(mul(tag('PREMIUM_CALL'), 3), tag('EXTRA_FEE'), 250)
+     * });
+     * ```
+     */
+    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 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.
+     *
+     * The middleware is framework-agnostic and works with Express, Fastify, and similar frameworks.
+     *
+     * @param config - Configuration object for the middleware
+     * @param config.extractor - Function that extracts userId and debitAmount from the request. Return null to skip tracking.
+     * @param config.whitelist - Optional array of endpoint patterns to track. Supports wildcards:
+     *                            - Exact match: /api/users
+     *                            - Single segment (*): /api/* matches /api/users but not /api/users/123
+     *                            - Multi-segment (**): /api/** matches any path starting with /api/
+     *                            - Mixed: /api/star/profile, **.php
+     *                            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
+     *
+     * @example
+     * ```typescript
+     * // Track all endpoints
+     * app.use(scrawn.middlewareEventConsumer({
+     *   extractor: (req) => ({
+     *     userId: req.user.id,
+     *     debitAmount: 1
+     *   })
+     * }));
+     *
+     * // Track only specific endpoints with wildcards
+     * app.use(scrawn.middlewareEventConsumer({
+     *   extractor: (req) => ({
+     *     userId: req.headers['x-user-id'] as string,
+     *     debitAmount: req.body.tokens || 1
+     *   }),
+     *   whitelist: ['/api/generate', '/api/analyze', '/api/v1/*']
+     * }));
+     *
+     * // Exclude specific endpoints from tracking
+     * app.use(scrawn.middlewareEventConsumer({
+     *   extractor: (req) => ({
+     *     userId: req.user.id,
+     *     debitAmount: 1
+     *   }),
+     *   blacklist: ['/health', '/api/collect-payment', '/internal/**', '**.tmp']
+     * }));
+     * ```
+     */
+    middlewareEventConsumer(config: MiddlewareEventConfig<TTags>): (req: MiddlewareRequest, res: MiddlewareResponse, next: MiddlewareNext) => Promise<void>;
+    /**
+     * Collect payment by creating a checkout link for a user.
+     *
+     * Generates a payment checkout link for the specified user via the Scrawn payment service.
+     * The checkout link can be used to direct users to complete their payment.
+     *
+     * @param userId - Unique identifier of the user to collect payment from
+     * @returns A promise that resolves to the checkout link URL
+     * @throws Error if the gRPC call fails or if authentication is invalid
+     *
+     * @example
+     * ```typescript
+     * const checkoutLink = await scrawn.collectPayment('user_abc123');
+     * // Returns: 'https://checkout.scrawn.dev/...'
+     * // Redirect user to this URL to complete payment
+     * ```
+     */
+    collectPayment(userId: string): Promise<string>;
+    /**
+     * Internal method to consume and process an event.
+     *
+     * This method:
+     * 1. Validates authentication
+     * 2. Fetches/caches credentials
+     * 3. Executes any pre-run hooks
+     * 4. Processes the event via gRPC call to RegisterEvent
+     *
+     * @param payload - Event payload data
+     * @param authMethodName - Name of the auth method to use (must be in AuthRegistry)
+     * @param eventType - Type of event for categorization (RAW or MIDDLEWARE_CALL)
+     * @returns A promise that resolves when the event is processed
+     * @throws Error if auth method is not registered or gRPC call fails
+     *
+     * @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

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