@scrawn/core 0.0.6 → 0.0.7

package/dist/core/errors/index.d.ts

@@ -7,7 +7,7 @@
  * @example
  * ```typescript
  * try {
- *   await scrawn.sdkCallEventConsumer({ ... });
+ *   await scrawn.basicUsageEventConsumer({ ... });
  * } catch (error) {
  *   if (error instanceof ScrawnAuthenticationError) {
  *     console.error('Auth failed:', error.message);

package/dist/core/errors/index.js

@@ -7,7 +7,7 @@
  * @example
  * ```typescript
  * try {
- *   await scrawn.sdkCallEventConsumer({ ... });
+ *   await scrawn.basicUsageEventConsumer({ ... });
  * } catch (error) {
  *   if (error instanceof ScrawnAuthenticationError) {
  *     console.error('Auth failed:', error.message);

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

@@ -15,7 +15,7 @@
  * const exprString = serializeExpr(expr);
  *
  * // Use in event payload
- * await scrawn.sdkCallEventConsumer({
+ * await scrawn.basicUsageEventConsumer({
  *   userId: 'u123',
  *   debitExpr: expr
  * });

package/dist/core/pricing/index.js

@@ -15,7 +15,7 @@
  * const exprString = serializeExpr(expr);
  *
  * // Use in event payload
- * await scrawn.sdkCallEventConsumer({
+ * await scrawn.basicUsageEventConsumer({
  *   userId: 'u123',
  *   debitExpr: expr
  * });

package/dist/core/scrawn.d.ts

@@ -22,8 +22,8 @@ import type { StreamEventResponse } from "../gen/event/v1/event_pb.js";
  * });
  *
  * // Tags are compile-time checked
- * biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'PREMIUM_FEATURE' });
- * // biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'UNKNOWN' }); // Type error!
+ * biller.basicUsageEventConsumer({ userId: 'u123', debitTag: 'PREMIUM_FEATURE' });
+ * // biller.basicUsageEventConsumer({ userId: 'u123', debitTag: 'UNKNOWN' }); // Type error!
  * ```
  */
 export declare class Scrawn<TTags extends string = string, TExprs extends string = string> {
@@ -38,10 +38,14 @@ export declare class Scrawn<TTags extends string = string, TExprs extends string
     private apiKey;
     /** gRPC client for making type-safe API calls */
     private grpcClient;
+    /** Number of auto-retry attempts on retryable errors before falling back to onError */
+    private retryCount;
     /** 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 sleep;
+    private backoffMs;
     private notifyEventConsumerError;
     private notifyValidationError;
     /**
@@ -65,6 +69,7 @@ export declare class Scrawn<TTags extends string = string, TExprs extends string
         baseURL: string;
         secure?: boolean;
         credentials?: import("@grpc/grpc-js").ChannelCredentials;
+        retryCount?: number;
     });
     private parseURLToTarget;
     /**
@@ -99,13 +104,13 @@ export declare class Scrawn<TTags extends string = string, TExprs extends string
      * @example
      * ```typescript
      * // Reference a persisted expression
-     * biller.sdkCallEventConsumer({
+     * biller.basicUsageEventConsumer({
      *   userId: 'u123',
      *   debitExpr: biller.expr("MY_EXPR"),
      * });
      *
      * // Inline expression passthrough
-     * biller.sdkCallEventConsumer({
+     * biller.basicUsageEventConsumer({
      *   userId: 'u123',
      *   debitExpr: biller.expr(mul(biller.tag("PREMIUM_CALL"), 3)),
      * });
@@ -147,17 +152,19 @@ export declare class Scrawn<TTags extends string = string, TExprs extends string
      */
     private getCredsFor;
     /**
-     * Track an SDK call event.
+     * Track a basic usage event.
      *
-     * Records SDK usage to the Scrawn backend for billing tracking.
+     * Records basic 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 - The usage 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 payload.metadata - (Optional) Arbitrary metadata to associate with the event
      * @param options - Optional configuration
+     * @param options.eventId - (Optional) Override the auto-generated event ID
      * @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
      *
@@ -166,25 +173,26 @@ export declare class Scrawn<TTags extends string = string, TExprs extends string
      * import { add, mul, tag } from '@scrawn/core';
      *
      * // Using direct amount (500 cents = $5.00)
-     * await scrawn.sdkCallEventConsumer({
+     * await scrawn.basicUsageEventConsumer({
      *   userId: 'user_abc123',
      *   debitAmount: 500
      * });
      *
      * // Using price tag
-     * await scrawn.sdkCallEventConsumer({
+     * await scrawn.basicUsageEventConsumer({
      *   userId: 'user_abc123',
      *   debitTag: 'PREMIUM_FEATURE'
      * });
      *
      * // Using pricing expression: (PREMIUM_CALL * 3) + EXTRA_FEE + 250 cents
-     * await scrawn.sdkCallEventConsumer({
+     * await scrawn.basicUsageEventConsumer({
      *   userId: 'user_abc123',
      *   debitExpr: add(mul(tag('PREMIUM_CALL'), 3), tag('EXTRA_FEE'), 250)
      * });
      * ```
      */
-    sdkCallEventConsumer(payload: EventPayload<TTags>, options?: {
+    basicUsageEventConsumer(payload: EventPayload<TTags>, options?: {
+        eventId?: string;
         onError?: EventConsumerErrorCallback;
     }): Promise<void>;
     /**
@@ -271,6 +279,8 @@ export declare class Scrawn<TTags extends string = string, TExprs extends string
      * @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)
+     * @param eventId - Stable event ID (generated by caller, reused across retries)
+     * @param idempotencyKey - Stable idempotency key (generated by caller, reused across retries)
      * @returns A promise that resolves when the event is processed
      * @throws Error if auth method is not registered or gRPC call fails
      *
@@ -361,6 +371,12 @@ export interface ScrawnInitConfig {
     credentials?: import("@grpc/grpc-js").ChannelCredentials;
     tags?: readonly string[];
     expressions?: readonly string[];
+    /**
+     * Number of automatic retry attempts on transient network errors
+     * (UNAVAILABLE, DEADLINE_EXCEEDED). Defaults to 2. Set to 0 to disable.
+     * Each event also gets a manual `.retry()` context in the onError callback.
+     */
+    retryCount?: number;
 }
 /**
  * Create a type-safe Scrawn billing instance.
@@ -380,11 +396,11 @@ export interface ScrawnInitConfig {
  *   expressions: ["MY_EXPR"] as const,
  * });
  *
- * biller.sdkCallEventConsumer({
+ * biller.basicUsageEventConsumer({
  *   userId: 'u123',
  *   debitExpr: biller.expr("MY_EXPR"),          // persisted expression
  * });
- * biller.sdkCallEventConsumer({
+ * biller.basicUsageEventConsumer({
  *   userId: 'u123',
  *   debitExpr: mul(biller.tag("PREMIUM_CALL"), 3), // inline
  * });

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

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

package/dist/core/scrawn.js

@@ -5,12 +5,13 @@ import { forkAsyncIterable } from "../utils/forkAsyncIterable.js";
 import { EventPayloadSchema, AITokenUsagePayloadSchema, } from "./types/event.js";
 import { GrpcClient } from "./grpc/index.js";
 import { EventServiceClient } from "../gen/event/v1/event_grpc_pb.js";
-import { RegisterEventRequest, StreamEventRequest, EventType, SDKCallType, SDKCall, AITokenUsage, } from "../gen/event/v1/event_pb.js";
+import { RegisterEventRequest, StreamEventRequest, EventType, BasicUsageType, BasicUsage, AITokenUsage, } from "../gen/event/v1/event_pb.js";
 import { PaymentServiceClient } from "../gen/payment/v1/payment_grpc_pb.js";
 import { CreateCheckoutLinkRequest, } from "../gen/payment/v1/payment_pb.js";
-import { ScrawnConfigError, ScrawnValidationError, convertGrpcError, isScrawnError, } from "./errors/index.js";
+import { ScrawnConfigError, ScrawnValidationError, convertGrpcError, isScrawnError, isRetryableError, } from "./errors/index.js";
 import { serializeExpr, resolveTokens, prettyPrintExpr, tag as _tag } from "./pricing/index.js";
 import { ScrawnConfig } from "../config.js";
+import { randomUUID } from "node:crypto";
 const log = new ScrawnLogger("Scrawn");
 /**
  * Main SDK class for Scrawn billing infrastructure.
@@ -31,8 +32,8 @@ const log = new ScrawnLogger("Scrawn");
  * });
  *
  * // Tags are compile-time checked
- * biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'PREMIUM_FEATURE' });
- * // biller.sdkCallEventConsumer({ userId: 'u123', debitTag: 'UNKNOWN' }); // Type error!
+ * biller.basicUsageEventConsumer({ userId: 'u123', debitTag: 'PREMIUM_FEATURE' });
+ * // biller.basicUsageEventConsumer({ userId: 'u123', debitTag: 'UNKNOWN' }); // Type error!
  * ```
  */
 export class Scrawn {
@@ -44,6 +45,12 @@ export class Scrawn {
     get apikey() {
         return this.apiKey;
     }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    backoffMs(attempt) {
+        return Math.min(1000 * Math.pow(2, attempt), 8000);
+    }
     notifyEventConsumerError(error, onError) {
         const converted = isScrawnError(error) ? error : convertGrpcError(error);
         onError?.(converted);
@@ -90,6 +97,7 @@ export class Scrawn {
                 });
             }
             this.apiKey = config.apiKey;
+            this.retryCount = config.retryCount ?? 2;
             this.grpcClient = new GrpcClient(this.parseURLToTarget(config.baseURL), { secure: config.secure ?? true, credentials: config.credentials });
             this.registerAuthMethod("api", new ApiKeyAuth(this.apiKey));
         }
@@ -183,17 +191,19 @@ export class Scrawn {
         return creds;
     }
     /**
-     * Track an SDK call event.
+     * Track a basic usage event.
      *
-     * Records SDK usage to the Scrawn backend for billing tracking.
+     * Records basic 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 - The usage 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 payload.metadata - (Optional) Arbitrary metadata to associate with the event
      * @param options - Optional configuration
+     * @param options.eventId - (Optional) Override the auto-generated event ID
      * @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
      *
@@ -202,37 +212,38 @@ export class Scrawn {
      * import { add, mul, tag } from '@scrawn/core';
      *
      * // Using direct amount (500 cents = $5.00)
-     * await scrawn.sdkCallEventConsumer({
+     * await scrawn.basicUsageEventConsumer({
      *   userId: 'user_abc123',
      *   debitAmount: 500
      * });
      *
      * // Using price tag
-     * await scrawn.sdkCallEventConsumer({
+     * await scrawn.basicUsageEventConsumer({
      *   userId: 'user_abc123',
      *   debitTag: 'PREMIUM_FEATURE'
      * });
      *
      * // Using pricing expression: (PREMIUM_CALL * 3) + EXTRA_FEE + 250 cents
-     * await scrawn.sdkCallEventConsumer({
+     * await scrawn.basicUsageEventConsumer({
      *   userId: 'user_abc123',
      *   debitExpr: add(mul(tag('PREMIUM_CALL'), 3), tag('EXTRA_FEE'), 250)
      * });
      * ```
      */
-    async sdkCallEventConsumer(payload, options) {
+    async basicUsageEventConsumer(payload, options) {
         const rawPayload = {
             userId: payload.userId,
             debitAmount: payload.debitAmount,
             debitTag: payload.debitTag,
             debitExpr: payload.debitExpr?._expr,
+            metadata: payload.metadata,
         };
         const validationResult = EventPayloadSchema.safeParse(rawPayload);
         if (!validationResult.success) {
             const errors = validationResult.error.issues
                 .map((e) => `${e.path.join(".")}: ${e.message}`)
                 .join(", ");
-            log.error(`Invalid payload for sdkCallEventConsumer: ${errors}`);
+            log.error(`Invalid payload for basicUsageEventConsumer: ${errors}`);
             const error = new ScrawnValidationError("Payload validation failed", {
                 details: {
                     errors: validationResult.error.issues.map((e) => ({
@@ -244,12 +255,34 @@ export class Scrawn {
             this.notifyValidationError(error, options?.onError);
             return;
         }
+        // Fixed identity for this event — survives retries
+        const eventId = options?.eventId ?? randomUUID();
+        const idempotencyKey = randomUUID();
+        const attempt = () => this.consumeEvent(validationResult.data, "api", "RAW", eventId, idempotencyKey);
         try {
-            await this.consumeEvent(validationResult.data, "api", "SDK_CALL");
+            await attempt();
         }
         catch (error) {
-            log.error(`Failed to track sdkCallEventConsumer event: ${error instanceof Error ? error.message : "Unknown error"}`);
-            this.notifyEventConsumerError(error, options?.onError);
+            log.error(`Failed to track basicUsageEventConsumer event: ${error instanceof Error ? error.message : "Unknown error"}`);
+            if (options?.onError) {
+                const converted = isScrawnError(error)
+                    ? error
+                    : convertGrpcError(error);
+                const retryContext = {
+                    retry: async () => {
+                        try {
+                            await attempt();
+                        }
+                        catch (retryError) {
+                            const convertedRetry = isScrawnError(retryError)
+                                ? retryError
+                                : convertGrpcError(retryError);
+                            options.onError(convertedRetry, retryContext);
+                        }
+                    },
+                };
+                options.onError(converted, retryContext);
+            }
             return;
         }
     }
@@ -335,6 +368,7 @@ export class Scrawn {
                     debitAmount: extractedPayload.debitAmount,
                     debitTag: extractedPayload.debitTag,
                     debitExpr: extractedPayload.debitExpr?._expr,
+                    metadata: extractedPayload.metadata,
                 };
                 const validationResult = EventPayloadSchema.safeParse(rawPayload);
                 if (!validationResult.success) {
@@ -353,7 +387,9 @@ export class Scrawn {
                     this.notifyValidationError(error, config.onError);
                     return next();
                 }
-                this.consumeEvent(validationResult.data, "api", "MIDDLEWARE_CALL").catch((error) => {
+                const eventId = randomUUID();
+                const idempotencyKey = randomUUID();
+                this.consumeEvent(validationResult.data, "api", "MIDDLEWARE_CALL", eventId, idempotencyKey).catch((error) => {
                     log.error(`Failed to track middleware event: ${error.message}`);
                     this.notifyEventConsumerError(error, config.onError);
                 });
@@ -422,12 +458,14 @@ export class Scrawn {
      * @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)
+     * @param eventId - Stable event ID (generated by caller, reused across retries)
+     * @param idempotencyKey - Stable idempotency key (generated by caller, reused across retries)
      * @returns A promise that resolves when the event is processed
      * @throws Error if auth method is not registered or gRPC call fails
      *
      * @internal
      */
-    async consumeEvent(payload, authMethodName, eventType) {
+    async consumeEvent(payload, authMethodName, eventType, eventId, idempotencyKey) {
         const auth = this.authMethods.get(authMethodName);
         if (!auth) {
             throw new ScrawnConfigError(`No auth registered for type ${authMethodName}`, {
@@ -439,52 +477,67 @@ export class Scrawn {
             await auth.preRun();
         // Get creds (from cache or fresh)
         const creds = await this.getCredsFor(authMethodName);
-        // Map event type to SDKCallType
-        const sdkCallType = eventType === "SDK_CALL" ? SDKCallType.RAW : SDKCallType.MIDDLEWARE_CALL;
-        try {
-            log.info(`Ingesting event (type: ${eventType}) with creds: ${JSON.stringify(creds)}, payload: ${JSON.stringify(payload)}`);
-            // Build debit field based on which debit option is provided
-            let debitField;
-            if (payload.debitAmount !== undefined) {
-                debitField = { case: "amount", value: payload.debitAmount };
-            }
-            else if (payload.debitTag !== undefined) {
-                debitField = { case: "tag", value: payload.debitTag };
-            }
-            else {
-                // debitExpr is defined (validated by schema)
-                const serialized = serializeExpr(payload.debitExpr);
-                log.debug(`Serialized pricing expression: ${serialized}\n${prettyPrintExpr(payload.debitExpr)}`);
-                debitField = {
-                    case: "expr",
-                    value: serialized,
-                };
-            }
-            const sdkCall = new SDKCall();
-            sdkCall.setSdkcalltype(sdkCallType);
-            if (debitField.case === "amount") {
-                sdkCall.setAmount(debitField.value);
-            }
-            else if (debitField.case === "tag") {
-                sdkCall.setTag(debitField.value);
+        // Map event type to BasicUsageType
+        const basicUsageType = eventType === "RAW" ? BasicUsageType.RAW : BasicUsageType.MIDDLEWARE_CALL;
+        // Build debit field based on which debit option is provided
+        let debitField;
+        if (payload.debitAmount !== undefined) {
+            debitField = { case: "amount", value: payload.debitAmount };
+        }
+        else if (payload.debitTag !== undefined) {
+            debitField = { case: "tag", value: payload.debitTag };
+        }
+        else {
+            const serialized = serializeExpr(payload.debitExpr);
+            log.debug(`Serialized pricing expression: ${serialized}\n${prettyPrintExpr(payload.debitExpr)}`);
+            debitField = {
+                case: "expr",
+                value: serialized,
+            };
+        }
+        // Retry loop for retryable failures
+        for (let attempt = 0;; attempt++) {
+            try {
+                log.info(`Ingesting event (type: ${eventType}) — attempt ${attempt + 1}`);
+                const basicUsage = new BasicUsage();
+                basicUsage.setBasicusagetype(basicUsageType);
+                if (debitField.case === "amount") {
+                    basicUsage.setAmount(debitField.value);
+                }
+                else if (debitField.case === "tag") {
+                    basicUsage.setTag(debitField.value);
+                }
+                else {
+                    basicUsage.setExpr(debitField.value);
+                }
+                if (payload.metadata) {
+                    basicUsage.setMetadata(JSON.stringify(payload.metadata));
+                }
+                const request = new RegisterEventRequest();
+                request.setType(EventType.BASIC_USAGE);
+                request.setUserid(payload.userId);
+                request.setEventid(eventId);
+                request.setIdempotencykey(idempotencyKey);
+                request.setBasicusage(basicUsage);
+                const response = await this.grpcClient
+                    .newCall(EventServiceClient, "registerEvent")
+                    .addMetadata("authorization", `Bearer ${creds.apiKey}`)
+                    .addPayload(request)
+                    .request();
+                log.info(`Event registered successfully: ${JSON.stringify(response)}`);
+                break;
             }
-            else {
-                sdkCall.setExpr(debitField.value);
+            catch (error) {
+                const converted = convertGrpcError(error);
+                if (attempt < this.retryCount && isRetryableError(converted)) {
+                    const delay = this.backoffMs(attempt);
+                    log.warn(`Retryable error on attempt ${attempt + 1}, retrying in ${delay}ms: ${converted.message}`);
+                    await this.sleep(delay);
+                    continue;
+                }
+                log.error(`Failed to register event: ${converted.message}`);
+                throw converted;
             }
-            const request = new RegisterEventRequest();
-            request.setType(EventType.SDK_CALL);
-            request.setUserid(payload.userId);
-            request.setSdkcall(sdkCall);
-            const response = await this.grpcClient
-                .newCall(EventServiceClient, "registerEvent")
-                .addMetadata("authorization", `Bearer ${creds.apiKey}`)
-                .addPayload(request)
-                .request();
-            log.info(`Event registered successfully: ${JSON.stringify(response)}`);
-        }
-        catch (error) {
-            log.error(`Failed to register event: ${error instanceof Error ? error.message : "Unknown error"}`);
-            throw convertGrpcError(error);
         }
         if (auth.postRun)
             await auth.postRun();
@@ -520,8 +573,8 @@ export class Scrawn {
      *     model: 'gpt-4',
      *     inputTokens: 100,
      *     outputTokens: 50,
-     *     inputDebit: { amount: 0.003 },
-     *     outputDebit: { amount: 0.006 }
+     *     inputDebit: { amount: 1 },
+     *     outputDebit: { amount: 1 }
      *   };
      * }
      *
@@ -617,6 +670,16 @@ export class Scrawn {
                     tag: payload.outputDebit.tag,
                     expr: payload.outputDebit.expr?._expr,
                 },
+                metadata: payload.metadata,
+                provider: payload.provider,
+                inputCacheTokens: payload.inputCacheTokens,
+                inputCacheDebit: payload.inputCacheDebit
+                    ? {
+                        amount: payload.inputCacheDebit.amount,
+                        tag: payload.inputCacheDebit.tag,
+                        expr: payload.inputCacheDebit.expr?._expr,
+                    }
+                    : undefined,
             };
             // Validate each payload
             const validationResult = AITokenUsagePayloadSchema.safeParse(rawPayload);
@@ -710,9 +773,38 @@ export class Scrawn {
             else {
                 aiTokenUsage.setOutputexpr(outputDebit.value);
             }
+            // Set metadata on AITokenUsage if provided
+            if (validated.metadata) {
+                aiTokenUsage.setMetadata(JSON.stringify(validated.metadata));
+            }
+            // Set provider if provided
+            if (validated.provider) {
+                aiTokenUsage.setProvider(validated.provider);
+            }
+            // Set input cache tokens if provided
+            if (validated.inputCacheTokens !== undefined) {
+                aiTokenUsage.setInputcachetokens(validated.inputCacheTokens);
+            }
+            // Set input cache debit if provided
+            if (validated.inputCacheDebit) {
+                if (validated.inputCacheDebit.amount !== undefined) {
+                    aiTokenUsage.setInputcacheamount(validated.inputCacheDebit.amount);
+                }
+                else if (validated.inputCacheDebit.tag !== undefined) {
+                    aiTokenUsage.setInputcachetag(validated.inputCacheDebit.tag);
+                }
+                else if (validated.inputCacheDebit.expr) {
+                    const resolved = resolveTokens(validated.inputCacheDebit.expr, tokenContext);
+                    aiTokenUsage.setInputcacheexpr(serializeExpr(resolved));
+                }
+            }
+            const eventId = randomUUID();
+            const idempotencyKey = randomUUID();
             const request = new StreamEventRequest();
             request.setType(EventType.AI_TOKEN_USAGE);
             request.setUserid(validated.userId);
+            request.setEventid(eventId);
+            request.setIdempotencykey(idempotencyKey);
             request.setAitokenusage(aiTokenUsage);
             yield request;
         }
@@ -724,6 +816,7 @@ export function createScrawn(config) {
         baseURL: config.baseURL,
         secure: config.secure,
         credentials: config.credentials,
+        retryCount: config.retryCount,
     });
 }
 //# sourceMappingURL=scrawn.js.map