@aipricinglab/sdk 0.1.0 → 0.2.0

package/README.md

@@ -122,7 +122,7 @@ await apl.track('user_abc123', 'video.runway-gen3', 8);
 ## Check without charging
 
 ```ts
-const { allowed, reasons } = await apl.canUse('user_abc123', 'image.flux-pro');
+const { allowed, matched, reasons } = await apl.canUse('user_abc123', 'image.flux-pro');
 
 if (!allowed) {
   return showUpgradePrompt(reasons);
@@ -137,6 +137,17 @@ if (await apl.can('user_abc123', 'image.flux-pro')) {
 }
 ```
 
+### Fail-closed by default
+
+`canUse` and `reserve` return `{ allowed: false, matched: false }` when:
+
+- The `event` string doesn't match any limit group on the user's plan → `reasons: ['unmatched_event']` (typo, missing limit group, or mistyped event name).
+- The user has no active subscription on file → `reasons: ['no_subscription']` (you forgot to call `upsertSubscription`).
+
+This is intentional — silent fail-open is a footgun. To make typos and missing setup obvious during development, the SDK also `console.warn`s once per call when `matched === false` and `process.env.NODE_ENV !== 'production'`. Production stays silent.
+
+Every event sent to `track()` is *recorded regardless* (even unmatched / no-subscription) so you can inspect them in the dashboard's **Events** activity feed, which shows status badges (Counted / Not matched / Limit reached / No plan) and "did you mean?" suggestions for typos.
+
 ## Variant-gated plan rows
 
 Some plans gate a model by output tier — e.g. *"100 standard images, 10 4K images"*. Pass the `variant` key in `metadata` so the right bucket is incremented:
@@ -183,6 +194,20 @@ await apl.upsertSubscription({
 });
 ```
 
+Calling `upsertSubscription` with the **same** `planId` the user is already on is a no-op: counters keep ticking, `started_at` is preserved, periods don't reset. Safe to call on every login or webhook retry.
+
+### Plan-change semantics
+
+When you move a user onto a *different* plan mid-period, each limit group on the new plan picks one of three behaviors (configured per-plan in the dashboard's **Advanced** section):
+
+| Mode | What happens to counters at switch time |
+|---|---|
+| **`carry`** *(default)* | Existing counters with the same limit-group ID continue. Brand-new groups start at 0. |
+| **`reset`** | Counters for the new plan's groups are wiped — the user starts the period from 0. |
+| **`block`** | Counters are pre-filled to quota; `canUse` / `reserve` return `limit_reached` until the next period rollover. |
+
+This lets you choose the right cancellation/upgrade UX — generous (`carry`), clean-slate (`reset`), or anti-abuse (`block`, which closes the "free→pro→cancel→fresh free quota" cycling exploit).
+
 ## Error handling
 
 Every method throws a typed `AiPricingLabError` on failure:
@@ -205,7 +230,7 @@ try {
 | Method | Purpose |
 |---|---|
 | `track(userId, event, quantity?, metadata?)` | Record consumption. |
-| `canUse(userId, event, quantity?, metadata?)` | Check if allowed; returns `{ allowed, reasons, details }`. |
+| `canUse(userId, event, quantity?, metadata?)` | Check if allowed; returns `{ allowed, matched, reasons, details }`. |
 | `can(userId, event, quantity?, metadata?)` | Boolean shorthand for `canUse`. |
 | `reserve(userId, event, quantity?, metadata?)` | Atomically hold quota; returns a `reservationId`. |
 | `commit(reservationId)` | Confirm a reservation. |

package/dist/index.d.mts

@@ -3,12 +3,14 @@ interface MatchRule {
     event: string;
     metadata?: Record<string, string> | undefined;
 }
+type OnPlanChange = 'carry' | 'reset' | 'block';
 interface LimitGroup {
     id: string;
     label: string;
     unit: LimitUnit;
     quota: number;
     matches: MatchRule[];
+    onPlanChange?: OnPlanChange;
 }
 interface PlanLimits {
     groups: LimitGroup[];
@@ -16,8 +18,11 @@ interface PlanLimits {
 type PeriodType = 'daily' | 'weekly' | 'monthly' | 'lifetime';
 type PeriodAnchor = 'subscription_start' | 'calendar';
 type EventMetadata = Record<string, string>;
+type MatchStatus = 'matched' | 'unmatched' | 'blocked' | 'no_subscription';
 interface TrackResponseData {
     eventId: string;
+    matchStatus: MatchStatus;
+    matchedGroupIds: string[];
     counters: CounterSummary[];
 }
 interface CounterSummary {
@@ -25,7 +30,7 @@ interface CounterSummary {
     count: number;
     costCents: number;
 }
-type ErrorCode = 'not_found' | 'invalid_key' | 'requires_secret_key' | 'limit_reached' | 'workspace_limit_reached' | 'invalid_request' | 'reservation_expired' | 'reservation_not_pending' | 'internal_error' | 'not_implemented';
+type ErrorCode = 'not_found' | 'invalid_key' | 'requires_secret_key' | 'limit_reached' | 'unmatched_event' | 'no_subscription' | 'workspace_limit_reached' | 'invalid_request' | 'reservation_expired' | 'reservation_not_pending' | 'internal_error' | 'not_implemented';
 interface ApiError {
     code: ErrorCode;
     message: string;
@@ -41,6 +46,7 @@ interface ApiFail {
 type ApiResponse<T> = ApiOk<T> | ApiFail;
 interface CanUseResponseData {
     allowed: boolean;
+    matched: boolean;
     reasons: string[];
     details: {
         groupId: string;
@@ -51,6 +57,7 @@ interface CanUseResponseData {
 }
 interface ReserveResponseData {
     allowed: boolean;
+    matched: boolean;
     reservationId?: string;
     expiresAt?: string;
     reasons?: string[];
@@ -88,7 +95,7 @@ declare class AiPricingLabClient {
      * Record that a user consumed something.
      *
      * `metadata` is matched against the `metadata` filters on plan match rules.
-     * The dashboard uses one reserved key — **`variant`** — when a plan row gates
+     * The dashboard uses one reserved key - **`variant`** - when a plan row gates
      * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,
      * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated
      * buckets count the event:
@@ -102,7 +109,7 @@ declare class AiPricingLabClient {
      * Use `.can()` if you only need the boolean.
      *
      * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-     * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+     * the model to a specific output tier - see {@link AiPricingLabClient.track}.
      */
     canUse(userId: string, event: string, quantity?: number, metadata?: EventMetadata): Promise<CanUseResponseData>;
     /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */
@@ -112,7 +119,7 @@ declare class AiPricingLabClient {
      * On success call `commit(reservationId)`, on failure call `release(reservationId)`.
      *
      * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-     * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+     * the model to a specific output tier - see {@link AiPricingLabClient.track}.
      */
     reserve(userId: string, event: string, quantity?: number, metadata?: EventMetadata): Promise<ReserveResponseData>;
     /** Confirm a reservation after a successful AI call. */
@@ -122,7 +129,7 @@ declare class AiPricingLabClient {
     /**
      * Get current usage counters for a user.
      *
-     * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys — that endpoint
+     * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys - that endpoint
      * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.
      */
     usage(userId: string, event?: string): Promise<UsageResponseData>;

package/dist/index.d.ts

@@ -3,12 +3,14 @@ interface MatchRule {
     event: string;
     metadata?: Record<string, string> | undefined;
 }
+type OnPlanChange = 'carry' | 'reset' | 'block';
 interface LimitGroup {
     id: string;
     label: string;
     unit: LimitUnit;
     quota: number;
     matches: MatchRule[];
+    onPlanChange?: OnPlanChange;
 }
 interface PlanLimits {
     groups: LimitGroup[];
@@ -16,8 +18,11 @@ interface PlanLimits {
 type PeriodType = 'daily' | 'weekly' | 'monthly' | 'lifetime';
 type PeriodAnchor = 'subscription_start' | 'calendar';
 type EventMetadata = Record<string, string>;
+type MatchStatus = 'matched' | 'unmatched' | 'blocked' | 'no_subscription';
 interface TrackResponseData {
     eventId: string;
+    matchStatus: MatchStatus;
+    matchedGroupIds: string[];
     counters: CounterSummary[];
 }
 interface CounterSummary {
@@ -25,7 +30,7 @@ interface CounterSummary {
     count: number;
     costCents: number;
 }
-type ErrorCode = 'not_found' | 'invalid_key' | 'requires_secret_key' | 'limit_reached' | 'workspace_limit_reached' | 'invalid_request' | 'reservation_expired' | 'reservation_not_pending' | 'internal_error' | 'not_implemented';
+type ErrorCode = 'not_found' | 'invalid_key' | 'requires_secret_key' | 'limit_reached' | 'unmatched_event' | 'no_subscription' | 'workspace_limit_reached' | 'invalid_request' | 'reservation_expired' | 'reservation_not_pending' | 'internal_error' | 'not_implemented';
 interface ApiError {
     code: ErrorCode;
     message: string;
@@ -41,6 +46,7 @@ interface ApiFail {
 type ApiResponse<T> = ApiOk<T> | ApiFail;
 interface CanUseResponseData {
     allowed: boolean;
+    matched: boolean;
     reasons: string[];
     details: {
         groupId: string;
@@ -51,6 +57,7 @@ interface CanUseResponseData {
 }
 interface ReserveResponseData {
     allowed: boolean;
+    matched: boolean;
     reservationId?: string;
     expiresAt?: string;
     reasons?: string[];
@@ -88,7 +95,7 @@ declare class AiPricingLabClient {
      * Record that a user consumed something.
      *
      * `metadata` is matched against the `metadata` filters on plan match rules.
-     * The dashboard uses one reserved key — **`variant`** — when a plan row gates
+     * The dashboard uses one reserved key - **`variant`** - when a plan row gates
      * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,
      * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated
      * buckets count the event:
@@ -102,7 +109,7 @@ declare class AiPricingLabClient {
      * Use `.can()` if you only need the boolean.
      *
      * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-     * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+     * the model to a specific output tier - see {@link AiPricingLabClient.track}.
      */
     canUse(userId: string, event: string, quantity?: number, metadata?: EventMetadata): Promise<CanUseResponseData>;
     /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */
@@ -112,7 +119,7 @@ declare class AiPricingLabClient {
      * On success call `commit(reservationId)`, on failure call `release(reservationId)`.
      *
      * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-     * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+     * the model to a specific output tier - see {@link AiPricingLabClient.track}.
      */
     reserve(userId: string, event: string, quantity?: number, metadata?: EventMetadata): Promise<ReserveResponseData>;
     /** Confirm a reservation after a successful AI call. */
@@ -122,7 +129,7 @@ declare class AiPricingLabClient {
     /**
      * Get current usage counters for a user.
      *
-     * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys — that endpoint
+     * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys - that endpoint
      * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.
      */
     usage(userId: string, event?: string): Promise<UsageResponseData>;

package/dist/index.js

@@ -72,7 +72,7 @@ var AiPricingLabClient = class {
    * Record that a user consumed something.
    *
    * `metadata` is matched against the `metadata` filters on plan match rules.
-   * The dashboard uses one reserved key — **`variant`** — when a plan row gates
+   * The dashboard uses one reserved key - **`variant`** - when a plan row gates
    * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,
    * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated
    * buckets count the event:
@@ -93,15 +93,17 @@ var AiPricingLabClient = class {
    * Use `.can()` if you only need the boolean.
    *
    * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-   * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+   * the model to a specific output tier - see {@link AiPricingLabClient.track}.
    */
   async canUse(userId, event, quantity = 1, metadata) {
-    return request(this.baseUrl, this.apiKey, "POST", "/api/v1/can-use", {
+    const result = await request(this.baseUrl, this.apiKey, "POST", "/api/v1/can-use", {
       userId,
       event,
       quantity,
       metadata
     });
+    warnIfUnmatched("canUse", event, result);
+    return result;
   }
   /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */
   async can(userId, event, quantity = 1, metadata) {
@@ -113,15 +115,17 @@ var AiPricingLabClient = class {
    * On success call `commit(reservationId)`, on failure call `release(reservationId)`.
    *
    * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-   * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+   * the model to a specific output tier - see {@link AiPricingLabClient.track}.
    */
   async reserve(userId, event, quantity = 1, metadata) {
-    return request(this.baseUrl, this.apiKey, "POST", "/api/v1/reserve", {
+    const result = await request(this.baseUrl, this.apiKey, "POST", "/api/v1/reserve", {
       userId,
       event,
       quantity,
       metadata
     });
+    warnIfUnmatched("reserve", event, result);
+    return result;
   }
   /** Confirm a reservation after a successful AI call. */
   async commit(reservationId) {
@@ -138,7 +142,7 @@ var AiPricingLabClient = class {
   /**
    * Get current usage counters for a user.
    *
-   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys — that endpoint
+   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys - that endpoint
    * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.
    */
   async usage(userId, event) {
@@ -161,6 +165,21 @@ var AiPricingLabClient = class {
 function createClient(opts) {
   return new AiPricingLabClient(opts);
 }
+function warnIfUnmatched(method, event, result) {
+  const proc = globalThis.process;
+  if (!proc || proc.env?.["NODE_ENV"] === "production") return;
+  if (result.matched !== false) return;
+  const reason = result.reasons?.[0];
+  if (reason === "unmatched_event") {
+    console.warn(
+      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (unmatched_event). No limit group on this user's plan covers this event_type. Check for typos or define a matching limit group in the dashboard.`
+    );
+  } else if (reason === "no_subscription") {
+    console.warn(
+      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (no_subscription). This user has no active subscription. Call upsertSubscription({ userId, planId }) before metering.`
+    );
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AiPricingLabClient,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/http.ts","../src/client.ts"],"sourcesContent":["export { AiPricingLabClient, createClient } from './client';\nexport type { ClientOptions } from './client';\nexport { AiPricingLabError } from './errors';\nexport type {\n  EventMetadata,\n  TrackResponseData,\n  CounterSummary,\n  CanUseResponseData,\n  ReserveResponseData,\n  UsageResponseData,\n  UpsertSubscriptionRequest,\n  UpsertSubscriptionResponseData,\n  LimitGroup,\n  LimitUnit,\n  MatchRule,\n  PlanLimits,\n  PeriodType,\n  PeriodAnchor,\n  ErrorCode,\n  ApiError,\n  ApiResponse,\n} from './types';\n","import type { ErrorCode } from './types';\n\nexport class AiPricingLabError extends Error {\n  readonly code: ErrorCode;\n  readonly status: number;\n\n  constructor(opts: { code: ErrorCode; message: string; status: number }) {\n    super(opts.message);\n    this.name = 'AiPricingLabError';\n    this.code = opts.code;\n    this.status = opts.status;\n  }\n}\n","// Phase 9: internal fetch wrapper\nimport type { ApiResponse, ErrorCode } from './types';\nimport { AiPricingLabError } from './errors';\n\nexport async function request<T>(\n  baseUrl: string,\n  apiKey: string,\n  method: string,\n  path: string,\n  body?: unknown,\n): Promise<T> {\n  const url = `${baseUrl.replace(/\\/$/, '')}${path}`;\n  const res = await fetch(url, {\n    method,\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${apiKey}`,\n    },\n    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),\n  });\n\n  const json = (await res.json()) as ApiResponse<T>;\n\n  if (!json.ok) {\n    throw new AiPricingLabError({\n      code: json.error.code as ErrorCode,\n      message: json.error.message,\n      status: res.status,\n    });\n  }\n\n  return json.data;\n}\n","import type {\n  TrackResponseData,\n  CanUseResponseData,\n  ReserveResponseData,\n  UsageResponseData,\n  UpsertSubscriptionRequest,\n  UpsertSubscriptionResponseData,\n  EventMetadata,\n} from './types';\nimport { request } from './http';\n\nexport interface ClientOptions {\n  apiKey: string;\n  baseUrl?: string;\n}\n\nexport class AiPricingLabClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n\n  constructor(opts: ClientOptions) {\n    this.apiKey = opts.apiKey;\n    this.baseUrl = opts.baseUrl ?? 'https://www.aipricinglab.space';\n  }\n\n  /**\n   * Record that a user consumed something.\n   *\n   * `metadata` is matched against the `metadata` filters on plan match rules.\n   * The dashboard uses one reserved key — **`variant`** — when a plan row gates\n   * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,\n   * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated\n   * buckets count the event:\n   *\n   *     await apl.track('user_123', 'image.gemini-3.1-image', 1, { variant: '4k' });\n   */\n  async track(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<TrackResponseData> {\n    return request<TrackResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/track', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /**\n   * Check if a user is allowed to perform an action.\n   * Returns `{ allowed, reasons, details }`.\n   * Use `.can()` if you only need the boolean.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier — see {@link AiPricingLabClient.track}.\n   */\n  async canUse(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<CanUseResponseData> {\n    return request<CanUseResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/can-use', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */\n  async can(userId: string, event: string, quantity = 1, metadata?: EventMetadata): Promise<boolean> {\n    const { allowed } = await this.canUse(userId, event, quantity, metadata);\n    return allowed;\n  }\n\n  /**\n   * Atomically reserve quota before doing the AI call.\n   * On success call `commit(reservationId)`, on failure call `release(reservationId)`.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier — see {@link AiPricingLabClient.track}.\n   */\n  async reserve(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<ReserveResponseData> {\n    return request<ReserveResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/reserve', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /** Confirm a reservation after a successful AI call. */\n  async commit(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/commit', {\n      reservationId,\n    });\n  }\n\n  /** Cancel a reservation after a failed AI call so quota is returned. */\n  async release(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/release', {\n      reservationId,\n    });\n  }\n\n  /**\n   * Get current usage counters for a user.\n   *\n   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys — that endpoint\n   * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.\n   */\n  async usage(userId: string, event?: string): Promise<UsageResponseData> {\n    const qs = new URLSearchParams({ userId });\n    if (event) qs.set('event', event);\n    const path = this.apiKey.startsWith('pk_live_')\n      ? `/api/v1/usage/me?${qs}`\n      : `/api/v1/usage?${qs}`;\n    return request<UsageResponseData>(this.baseUrl, this.apiKey, 'GET', path);\n  }\n\n  /** Assign or update a user's plan subscription. */\n  async upsertSubscription(\n    params: UpsertSubscriptionRequest,\n  ): Promise<UpsertSubscriptionResponseData> {\n    return request<UpsertSubscriptionResponseData>(\n      this.baseUrl,\n      this.apiKey,\n      'POST',\n      '/api/v1/subscriptions',\n      params,\n    );\n  }\n}\n\nexport function createClient(opts: ClientOptions): AiPricingLabClient {\n  return new AiPricingLabClient(opts);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/http.ts","../src/client.ts"],"sourcesContent":["export { AiPricingLabClient, createClient } from './client';\nexport type { ClientOptions } from './client';\nexport { AiPricingLabError } from './errors';\nexport type {\n  EventMetadata,\n  TrackResponseData,\n  CounterSummary,\n  CanUseResponseData,\n  ReserveResponseData,\n  UsageResponseData,\n  UpsertSubscriptionRequest,\n  UpsertSubscriptionResponseData,\n  LimitGroup,\n  LimitUnit,\n  MatchRule,\n  PlanLimits,\n  PeriodType,\n  PeriodAnchor,\n  ErrorCode,\n  ApiError,\n  ApiResponse,\n} from './types';\n","import type { ErrorCode } from './types';\n\nexport class AiPricingLabError extends Error {\n  readonly code: ErrorCode;\n  readonly status: number;\n\n  constructor(opts: { code: ErrorCode; message: string; status: number }) {\n    super(opts.message);\n    this.name = 'AiPricingLabError';\n    this.code = opts.code;\n    this.status = opts.status;\n  }\n}\n","// Phase 9: internal fetch wrapper\nimport type { ApiResponse, ErrorCode } from './types';\nimport { AiPricingLabError } from './errors';\n\nexport async function request<T>(\n  baseUrl: string,\n  apiKey: string,\n  method: string,\n  path: string,\n  body?: unknown,\n): Promise<T> {\n  const url = `${baseUrl.replace(/\\/$/, '')}${path}`;\n  const res = await fetch(url, {\n    method,\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${apiKey}`,\n    },\n    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),\n  });\n\n  const json = (await res.json()) as ApiResponse<T>;\n\n  if (!json.ok) {\n    throw new AiPricingLabError({\n      code: json.error.code as ErrorCode,\n      message: json.error.message,\n      status: res.status,\n    });\n  }\n\n  return json.data;\n}\n","import type {\n  TrackResponseData,\n  CanUseResponseData,\n  ReserveResponseData,\n  UsageResponseData,\n  UpsertSubscriptionRequest,\n  UpsertSubscriptionResponseData,\n  EventMetadata,\n} from './types';\nimport { request } from './http';\n\nexport interface ClientOptions {\n  apiKey: string;\n  baseUrl?: string;\n}\n\nexport class AiPricingLabClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n\n  constructor(opts: ClientOptions) {\n    this.apiKey = opts.apiKey;\n    this.baseUrl = opts.baseUrl ?? 'https://www.aipricinglab.space';\n  }\n\n  /**\n   * Record that a user consumed something.\n   *\n   * `metadata` is matched against the `metadata` filters on plan match rules.\n   * The dashboard uses one reserved key - **`variant`** - when a plan row gates\n   * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,\n   * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated\n   * buckets count the event:\n   *\n   *     await apl.track('user_123', 'image.gemini-3.1-image', 1, { variant: '4k' });\n   */\n  async track(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<TrackResponseData> {\n    return request<TrackResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/track', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /**\n   * Check if a user is allowed to perform an action.\n   * Returns `{ allowed, reasons, details }`.\n   * Use `.can()` if you only need the boolean.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier - see {@link AiPricingLabClient.track}.\n   */\n  async canUse(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<CanUseResponseData> {\n    const result = await request<CanUseResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/can-use', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n    warnIfUnmatched('canUse', event, result);\n    return result;\n  }\n\n  /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */\n  async can(userId: string, event: string, quantity = 1, metadata?: EventMetadata): Promise<boolean> {\n    const { allowed } = await this.canUse(userId, event, quantity, metadata);\n    return allowed;\n  }\n\n  /**\n   * Atomically reserve quota before doing the AI call.\n   * On success call `commit(reservationId)`, on failure call `release(reservationId)`.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier - see {@link AiPricingLabClient.track}.\n   */\n  async reserve(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<ReserveResponseData> {\n    const result = await request<ReserveResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/reserve', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n    warnIfUnmatched('reserve', event, result);\n    return result;\n  }\n\n  /** Confirm a reservation after a successful AI call. */\n  async commit(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/commit', {\n      reservationId,\n    });\n  }\n\n  /** Cancel a reservation after a failed AI call so quota is returned. */\n  async release(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/release', {\n      reservationId,\n    });\n  }\n\n  /**\n   * Get current usage counters for a user.\n   *\n   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys - that endpoint\n   * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.\n   */\n  async usage(userId: string, event?: string): Promise<UsageResponseData> {\n    const qs = new URLSearchParams({ userId });\n    if (event) qs.set('event', event);\n    const path = this.apiKey.startsWith('pk_live_')\n      ? `/api/v1/usage/me?${qs}`\n      : `/api/v1/usage?${qs}`;\n    return request<UsageResponseData>(this.baseUrl, this.apiKey, 'GET', path);\n  }\n\n  /** Assign or update a user's plan subscription. */\n  async upsertSubscription(\n    params: UpsertSubscriptionRequest,\n  ): Promise<UpsertSubscriptionResponseData> {\n    return request<UpsertSubscriptionResponseData>(\n      this.baseUrl,\n      this.apiKey,\n      'POST',\n      '/api/v1/subscriptions',\n      params,\n    );\n  }\n}\n\nexport function createClient(opts: ClientOptions): AiPricingLabClient {\n  return new AiPricingLabClient(opts);\n}\n\n// Surfaces typos and missing limit groups during development. Silent in\n// production so server logs aren't polluted on every legitimate \"user has\n// no subscription yet\" call.\nfunction warnIfUnmatched(\n  method: 'canUse' | 'reserve',\n  event: string,\n  result: { matched?: boolean; reasons?: string[] },\n): void {\n  // SDK ships with zero runtime deps and no @types/node, so feel our way\n  // through globalThis instead of referencing `process` directly. In the\n  // browser there's no process and the warn is silent — that's intentional.\n  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;\n  if (!proc || proc.env?.['NODE_ENV'] === 'production') return;\n  if (result.matched !== false) return;\n  const reason = result.reasons?.[0];\n  if (reason === 'unmatched_event') {\n    // eslint-disable-next-line no-console\n    console.warn(\n      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (unmatched_event). ` +\n      `No limit group on this user's plan covers this event_type. ` +\n      `Check for typos or define a matching limit group in the dashboard.`,\n    );\n  } else if (reason === 'no_subscription') {\n    // eslint-disable-next-line no-console\n    console.warn(\n      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (no_subscription). ` +\n      `This user has no active subscription. Call upsertSubscription({ userId, planId }) before metering.`,\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -44,7 +44,7 @@ var AiPricingLabClient = class {
    * Record that a user consumed something.
    *
    * `metadata` is matched against the `metadata` filters on plan match rules.
-   * The dashboard uses one reserved key — **`variant`** — when a plan row gates
+   * The dashboard uses one reserved key - **`variant`** - when a plan row gates
    * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,
    * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated
    * buckets count the event:
@@ -65,15 +65,17 @@ var AiPricingLabClient = class {
    * Use `.can()` if you only need the boolean.
    *
    * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-   * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+   * the model to a specific output tier - see {@link AiPricingLabClient.track}.
    */
   async canUse(userId, event, quantity = 1, metadata) {
-    return request(this.baseUrl, this.apiKey, "POST", "/api/v1/can-use", {
+    const result = await request(this.baseUrl, this.apiKey, "POST", "/api/v1/can-use", {
       userId,
       event,
       quantity,
       metadata
     });
+    warnIfUnmatched("canUse", event, result);
+    return result;
   }
   /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */
   async can(userId, event, quantity = 1, metadata) {
@@ -85,15 +87,17 @@ var AiPricingLabClient = class {
    * On success call `commit(reservationId)`, on failure call `release(reservationId)`.
    *
    * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates
-   * the model to a specific output tier — see {@link AiPricingLabClient.track}.
+   * the model to a specific output tier - see {@link AiPricingLabClient.track}.
    */
   async reserve(userId, event, quantity = 1, metadata) {
-    return request(this.baseUrl, this.apiKey, "POST", "/api/v1/reserve", {
+    const result = await request(this.baseUrl, this.apiKey, "POST", "/api/v1/reserve", {
       userId,
       event,
       quantity,
       metadata
     });
+    warnIfUnmatched("reserve", event, result);
+    return result;
   }
   /** Confirm a reservation after a successful AI call. */
   async commit(reservationId) {
@@ -110,7 +114,7 @@ var AiPricingLabClient = class {
   /**
    * Get current usage counters for a user.
    *
-   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys — that endpoint
+   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys - that endpoint
    * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.
    */
   async usage(userId, event) {
@@ -133,6 +137,21 @@ var AiPricingLabClient = class {
 function createClient(opts) {
   return new AiPricingLabClient(opts);
 }
+function warnIfUnmatched(method, event, result) {
+  const proc = globalThis.process;
+  if (!proc || proc.env?.["NODE_ENV"] === "production") return;
+  if (result.matched !== false) return;
+  const reason = result.reasons?.[0];
+  if (reason === "unmatched_event") {
+    console.warn(
+      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (unmatched_event). No limit group on this user's plan covers this event_type. Check for typos or define a matching limit group in the dashboard.`
+    );
+  } else if (reason === "no_subscription") {
+    console.warn(
+      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (no_subscription). This user has no active subscription. Call upsertSubscription({ userId, planId }) before metering.`
+    );
+  }
+}
 export {
   AiPricingLabClient,
   AiPricingLabError,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/http.ts","../src/client.ts"],"sourcesContent":["import type { ErrorCode } from './types';\n\nexport class AiPricingLabError extends Error {\n  readonly code: ErrorCode;\n  readonly status: number;\n\n  constructor(opts: { code: ErrorCode; message: string; status: number }) {\n    super(opts.message);\n    this.name = 'AiPricingLabError';\n    this.code = opts.code;\n    this.status = opts.status;\n  }\n}\n","// Phase 9: internal fetch wrapper\nimport type { ApiResponse, ErrorCode } from './types';\nimport { AiPricingLabError } from './errors';\n\nexport async function request<T>(\n  baseUrl: string,\n  apiKey: string,\n  method: string,\n  path: string,\n  body?: unknown,\n): Promise<T> {\n  const url = `${baseUrl.replace(/\\/$/, '')}${path}`;\n  const res = await fetch(url, {\n    method,\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${apiKey}`,\n    },\n    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),\n  });\n\n  const json = (await res.json()) as ApiResponse<T>;\n\n  if (!json.ok) {\n    throw new AiPricingLabError({\n      code: json.error.code as ErrorCode,\n      message: json.error.message,\n      status: res.status,\n    });\n  }\n\n  return json.data;\n}\n","import type {\n  TrackResponseData,\n  CanUseResponseData,\n  ReserveResponseData,\n  UsageResponseData,\n  UpsertSubscriptionRequest,\n  UpsertSubscriptionResponseData,\n  EventMetadata,\n} from './types';\nimport { request } from './http';\n\nexport interface ClientOptions {\n  apiKey: string;\n  baseUrl?: string;\n}\n\nexport class AiPricingLabClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n\n  constructor(opts: ClientOptions) {\n    this.apiKey = opts.apiKey;\n    this.baseUrl = opts.baseUrl ?? 'https://www.aipricinglab.space';\n  }\n\n  /**\n   * Record that a user consumed something.\n   *\n   * `metadata` is matched against the `metadata` filters on plan match rules.\n   * The dashboard uses one reserved key — **`variant`** — when a plan row gates\n   * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,\n   * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated\n   * buckets count the event:\n   *\n   *     await apl.track('user_123', 'image.gemini-3.1-image', 1, { variant: '4k' });\n   */\n  async track(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<TrackResponseData> {\n    return request<TrackResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/track', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /**\n   * Check if a user is allowed to perform an action.\n   * Returns `{ allowed, reasons, details }`.\n   * Use `.can()` if you only need the boolean.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier — see {@link AiPricingLabClient.track}.\n   */\n  async canUse(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<CanUseResponseData> {\n    return request<CanUseResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/can-use', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */\n  async can(userId: string, event: string, quantity = 1, metadata?: EventMetadata): Promise<boolean> {\n    const { allowed } = await this.canUse(userId, event, quantity, metadata);\n    return allowed;\n  }\n\n  /**\n   * Atomically reserve quota before doing the AI call.\n   * On success call `commit(reservationId)`, on failure call `release(reservationId)`.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier — see {@link AiPricingLabClient.track}.\n   */\n  async reserve(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<ReserveResponseData> {\n    return request<ReserveResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/reserve', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /** Confirm a reservation after a successful AI call. */\n  async commit(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/commit', {\n      reservationId,\n    });\n  }\n\n  /** Cancel a reservation after a failed AI call so quota is returned. */\n  async release(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/release', {\n      reservationId,\n    });\n  }\n\n  /**\n   * Get current usage counters for a user.\n   *\n   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys — that endpoint\n   * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.\n   */\n  async usage(userId: string, event?: string): Promise<UsageResponseData> {\n    const qs = new URLSearchParams({ userId });\n    if (event) qs.set('event', event);\n    const path = this.apiKey.startsWith('pk_live_')\n      ? `/api/v1/usage/me?${qs}`\n      : `/api/v1/usage?${qs}`;\n    return request<UsageResponseData>(this.baseUrl, this.apiKey, 'GET', path);\n  }\n\n  /** Assign or update a user's plan subscription. */\n  async upsertSubscription(\n    params: UpsertSubscriptionRequest,\n  ): Promise<UpsertSubscriptionResponseData> {\n    return request<UpsertSubscriptionResponseData>(\n      this.baseUrl,\n      this.apiKey,\n      'POST',\n      '/api/v1/subscriptions',\n      params,\n    );\n  }\n}\n\nexport function createClient(opts: ClientOptions): AiPricingLabClient {\n  return new AiPricingLabClient(opts);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/errors.ts","../src/http.ts","../src/client.ts"],"sourcesContent":["import type { ErrorCode } from './types';\n\nexport class AiPricingLabError extends Error {\n  readonly code: ErrorCode;\n  readonly status: number;\n\n  constructor(opts: { code: ErrorCode; message: string; status: number }) {\n    super(opts.message);\n    this.name = 'AiPricingLabError';\n    this.code = opts.code;\n    this.status = opts.status;\n  }\n}\n","// Phase 9: internal fetch wrapper\nimport type { ApiResponse, ErrorCode } from './types';\nimport { AiPricingLabError } from './errors';\n\nexport async function request<T>(\n  baseUrl: string,\n  apiKey: string,\n  method: string,\n  path: string,\n  body?: unknown,\n): Promise<T> {\n  const url = `${baseUrl.replace(/\\/$/, '')}${path}`;\n  const res = await fetch(url, {\n    method,\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${apiKey}`,\n    },\n    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),\n  });\n\n  const json = (await res.json()) as ApiResponse<T>;\n\n  if (!json.ok) {\n    throw new AiPricingLabError({\n      code: json.error.code as ErrorCode,\n      message: json.error.message,\n      status: res.status,\n    });\n  }\n\n  return json.data;\n}\n","import type {\n  TrackResponseData,\n  CanUseResponseData,\n  ReserveResponseData,\n  UsageResponseData,\n  UpsertSubscriptionRequest,\n  UpsertSubscriptionResponseData,\n  EventMetadata,\n} from './types';\nimport { request } from './http';\n\nexport interface ClientOptions {\n  apiKey: string;\n  baseUrl?: string;\n}\n\nexport class AiPricingLabClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n\n  constructor(opts: ClientOptions) {\n    this.apiKey = opts.apiKey;\n    this.baseUrl = opts.baseUrl ?? 'https://www.aipricinglab.space';\n  }\n\n  /**\n   * Record that a user consumed something.\n   *\n   * `metadata` is matched against the `metadata` filters on plan match rules.\n   * The dashboard uses one reserved key - **`variant`** - when a plan row gates\n   * a model to a specific output tier (e.g. image quality `1k`/`2k`/`4k`,\n   * video tier `standard`/`fast`/`lite`). Pass it through so variant-gated\n   * buckets count the event:\n   *\n   *     await apl.track('user_123', 'image.gemini-3.1-image', 1, { variant: '4k' });\n   */\n  async track(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<TrackResponseData> {\n    return request<TrackResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/track', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n  }\n\n  /**\n   * Check if a user is allowed to perform an action.\n   * Returns `{ allowed, reasons, details }`.\n   * Use `.can()` if you only need the boolean.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier - see {@link AiPricingLabClient.track}.\n   */\n  async canUse(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<CanUseResponseData> {\n    const result = await request<CanUseResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/can-use', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n    warnIfUnmatched('canUse', event, result);\n    return result;\n  }\n\n  /** Shorthand: returns `true` if allowed, `false` if the user hit a limit. */\n  async can(userId: string, event: string, quantity = 1, metadata?: EventMetadata): Promise<boolean> {\n    const { allowed } = await this.canUse(userId, event, quantity, metadata);\n    return allowed;\n  }\n\n  /**\n   * Atomically reserve quota before doing the AI call.\n   * On success call `commit(reservationId)`, on failure call `release(reservationId)`.\n   *\n   * Pass `metadata.variant` (e.g. `'4k'`, `'standard'`) when a plan row gates\n   * the model to a specific output tier - see {@link AiPricingLabClient.track}.\n   */\n  async reserve(\n    userId: string,\n    event: string,\n    quantity = 1,\n    metadata?: EventMetadata,\n  ): Promise<ReserveResponseData> {\n    const result = await request<ReserveResponseData>(this.baseUrl, this.apiKey, 'POST', '/api/v1/reserve', {\n      userId,\n      event,\n      quantity,\n      metadata,\n    });\n    warnIfUnmatched('reserve', event, result);\n    return result;\n  }\n\n  /** Confirm a reservation after a successful AI call. */\n  async commit(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/commit', {\n      reservationId,\n    });\n  }\n\n  /** Cancel a reservation after a failed AI call so quota is returned. */\n  async release(reservationId: string): Promise<void> {\n    await request<Record<string, never>>(this.baseUrl, this.apiKey, 'POST', '/api/v1/release', {\n      reservationId,\n    });\n  }\n\n  /**\n   * Get current usage counters for a user.\n   *\n   * Routes to `/api/v1/usage/me` for public (`pk_live_`) keys - that endpoint\n   * is the only one that accepts public keys. Secret keys hit `/api/v1/usage`.\n   */\n  async usage(userId: string, event?: string): Promise<UsageResponseData> {\n    const qs = new URLSearchParams({ userId });\n    if (event) qs.set('event', event);\n    const path = this.apiKey.startsWith('pk_live_')\n      ? `/api/v1/usage/me?${qs}`\n      : `/api/v1/usage?${qs}`;\n    return request<UsageResponseData>(this.baseUrl, this.apiKey, 'GET', path);\n  }\n\n  /** Assign or update a user's plan subscription. */\n  async upsertSubscription(\n    params: UpsertSubscriptionRequest,\n  ): Promise<UpsertSubscriptionResponseData> {\n    return request<UpsertSubscriptionResponseData>(\n      this.baseUrl,\n      this.apiKey,\n      'POST',\n      '/api/v1/subscriptions',\n      params,\n    );\n  }\n}\n\nexport function createClient(opts: ClientOptions): AiPricingLabClient {\n  return new AiPricingLabClient(opts);\n}\n\n// Surfaces typos and missing limit groups during development. Silent in\n// production so server logs aren't polluted on every legitimate \"user has\n// no subscription yet\" call.\nfunction warnIfUnmatched(\n  method: 'canUse' | 'reserve',\n  event: string,\n  result: { matched?: boolean; reasons?: string[] },\n): void {\n  // SDK ships with zero runtime deps and no @types/node, so feel our way\n  // through globalThis instead of referencing `process` directly. In the\n  // browser there's no process and the warn is silent — that's intentional.\n  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;\n  if (!proc || proc.env?.['NODE_ENV'] === 'production') return;\n  if (result.matched !== false) return;\n  const reason = result.reasons?.[0];\n  if (reason === 'unmatched_event') {\n    // eslint-disable-next-line no-console\n    console.warn(\n      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (unmatched_event). ` +\n      `No limit group on this user's plan covers this event_type. ` +\n      `Check for typos or define a matching limit group in the dashboard.`,\n    );\n  } else if (reason === 'no_subscription') {\n    // eslint-disable-next-line no-console\n    console.warn(\n      `[AiPricingLab] ${method}(${JSON.stringify(event)}) returned matched: false (no_subscription). ` +\n      `This user has no active subscription. Call upsertSubscription({ userId, planId }) before metering.`,\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipricinglab/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Usage metering and limits SDK for AI-powered apps. Track LLM tokens, image generations, video seconds, and any other AI consumption — provider-agnostic.",
   "keywords": [
     "ai",