@uniforge/platform-core 0.1.0-alpha.2

package/dist/billing/index.d.cts

@@ -0,0 +1,213 @@
+/**
+ * Platform-agnostic billing types.
+ *
+ * These types define the billing model used across all platform adapters.
+ * Platform-specific adapters implement the BillingService interface with
+ * their own GraphQL mutations and API calls.
+ */
+/** Billing interval for recurring charges. */
+type PlanInterval = 'EVERY_30_DAYS' | 'ANNUAL';
+/** Subscription status lifecycle values. */
+type SubscriptionStatus = 'PENDING' | 'ACTIVE' | 'CANCELLED' | 'EXPIRED' | 'FROZEN' | 'DECLINED';
+/** Monetary value with currency code. */
+interface Money {
+    amount: string;
+    currencyCode: string;
+}
+/** Pricing configuration for a recurring plan charge. */
+interface RecurringPricing {
+    type: 'recurring';
+    price: Money;
+    interval: PlanInterval;
+}
+/** Pricing configuration for a usage-based charge. */
+interface UsagePricing {
+    type: 'usage';
+    cappedAmount: Money;
+    terms: string;
+}
+/** Union of pricing detail types. */
+type PlanPricing = RecurringPricing | UsagePricing;
+/** A line item within a subscription (one plan can have recurring + usage lines). */
+interface SubscriptionLineItem {
+    id: string;
+    plan: {
+        pricingDetails: PlanPricing;
+    };
+}
+/** Billing plan definition. */
+interface BillingPlan {
+    name: string;
+    description: string;
+    lineItems: PlanPricing[];
+    features: string[];
+    trialDays?: number;
+    isDefault?: boolean;
+    sortOrder?: number;
+}
+/** A subscription record stored in the database. */
+interface Subscription {
+    id: string;
+    shopDomain: string;
+    shopifySubscriptionId: string | null;
+    planName: string;
+    status: SubscriptionStatus;
+    currentPeriodEnd: Date | null;
+    trialEndsAt: Date | null;
+    confirmationUrl: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Input for creating a new subscription. */
+interface CreateSubscriptionInput {
+    shopDomain: string;
+    planName: string;
+    returnUrl: string;
+    trialDays?: number;
+    shopifySubscriptionId?: string;
+    confirmationUrl?: string;
+}
+/** Input for creating a usage record. */
+interface CreateUsageRecordInput {
+    subscriptionId: string;
+    description: string;
+    amount: string;
+    currencyCode?: string;
+    idempotencyKey?: string;
+}
+/** A usage record stored in the database. */
+interface UsageRecord {
+    id: string;
+    subscriptionId: string;
+    description: string;
+    amount: string;
+    currencyCode: string;
+    idempotencyKey: string | null;
+    createdAt: Date;
+}
+/** Filter options for querying usage records. */
+interface UsageRecordFilter {
+    subscriptionId: string;
+    startDate?: Date;
+    endDate?: Date;
+}
+
+/**
+ * Platform-agnostic billing service interface.
+ *
+ * Defines the contract for billing operations that platform adapters
+ * must implement. Core billing service provides the base implementation
+ * with Prisma persistence.
+ */
+
+/** Core billing service for subscription and usage management. */
+interface BillingService {
+    /** Create a new subscription record in the database. */
+    createSubscription(input: CreateSubscriptionInput): Promise<Subscription>;
+    /** Get a subscription by its internal ID. */
+    getSubscription(id: string): Promise<Subscription | null>;
+    /** Get the currently active subscription for a shop. */
+    getActiveSubscription(shopDomain: string): Promise<Subscription | null>;
+    /** List all subscriptions for a shop. */
+    listSubscriptions(shopDomain: string): Promise<Subscription[]>;
+    /** Update subscription status (e.g., from webhook callback). */
+    updateSubscriptionStatus(id: string, status: SubscriptionStatus): Promise<Subscription>;
+    /** Update a subscription by its Shopify subscription ID. */
+    updateSubscriptionByShopifyId(shopifySubscriptionId: string, updates: Partial<Pick<Subscription, 'status' | 'currentPeriodEnd'>>): Promise<Subscription | null>;
+    /** Cancel a subscription. */
+    cancelSubscription(id: string): Promise<Subscription>;
+    /** Create a usage record against a subscription. */
+    createUsageRecord(input: CreateUsageRecordInput): Promise<UsageRecord>;
+    /** Get usage records with optional date range filtering. */
+    getUsageRecords(filter: UsageRecordFilter): Promise<UsageRecord[]>;
+    /** Calculate total usage amount for a subscription within a date range. */
+    calculateTotalUsage(filter: UsageRecordFilter): Promise<string>;
+}
+/** Plan registry for managing available billing plans. */
+interface PlanRegistry {
+    /** Register a billing plan. */
+    register(plan: BillingPlan): void;
+    /** Get a plan by name. */
+    get(name: string): BillingPlan | undefined;
+    /** List all registered plans (sorted by sortOrder). */
+    list(): BillingPlan[];
+    /** Get the default plan (if any). */
+    getDefault(): BillingPlan | undefined;
+}
+/** Platform-specific billing adapter for GraphQL operations. */
+interface PlatformBillingAdapter {
+    /** Create a subscription via the platform's API (e.g., Shopify GraphQL). */
+    createPlatformSubscription(input: {
+        shop: string;
+        accessToken: string;
+        planName: string;
+        lineItems: BillingPlan['lineItems'];
+        returnUrl: string;
+        trialDays?: number;
+    }): Promise<{
+        shopifySubscriptionId: string;
+        confirmationUrl: string;
+    }>;
+    /** Create a usage record via the platform's API. */
+    createPlatformUsageRecord(input: {
+        shop: string;
+        accessToken: string;
+        subscriptionLineItemId: string;
+        amount: string;
+        currencyCode: string;
+        description: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Cancel a subscription via the platform's API. */
+    cancelPlatformSubscription(input: {
+        shop: string;
+        accessToken: string;
+        subscriptionId: string;
+    }): Promise<void>;
+}
+
+/**
+ * Feature gate interfaces for plan-based feature gating.
+ *
+ * Provides a way to restrict features based on the merchant's
+ * active billing plan. Used by route middleware to enforce
+ * plan-level access control.
+ */
+
+/** Maps plan names to the features they include. */
+type PlanFeatureMap = Record<string, string[]>;
+/** Definition of a gated feature. */
+interface FeatureDefinition {
+    name: string;
+    description: string;
+    requiredPlan?: string;
+}
+/** Configuration for the feature gate middleware. */
+interface FeatureGateConfig {
+    /** Map of plan names to their included features. */
+    planFeatures: PlanFeatureMap;
+    /** Function to retrieve the active subscription's plan for a shop. */
+    getPlanForShop: (shopDomain: string) => Promise<BillingPlan | null>;
+    /** Features available to all shops regardless of plan (free tier). */
+    freeFeatures?: string[];
+}
+/** Feature gate middleware for checking plan-based access. */
+interface FeatureGateMiddleware {
+    /** Check if a shop has access to a feature. */
+    hasFeature(shopDomain: string, featureName: string): Promise<boolean>;
+    /** Require a feature — throws FeatureGateError if not available. */
+    requireFeature(shopDomain: string, featureName: string): Promise<void>;
+    /** Get all available features for a shop based on their plan. */
+    getAvailableFeatures(shopDomain: string): Promise<string[]>;
+    /** Get the current plan name for a shop (null if no active subscription). */
+    getCurrentPlanName(shopDomain: string): Promise<string | null>;
+}
+/** Error thrown when a feature is not available for the current plan. */
+declare class FeatureGateError extends Error {
+    readonly featureName: string;
+    readonly currentPlan: string | null;
+    constructor(featureName: string, currentPlan: string | null);
+}
+
+export { type BillingPlan, type BillingService, type CreateSubscriptionInput, type CreateUsageRecordInput, type FeatureDefinition, type FeatureGateConfig, FeatureGateError, type FeatureGateMiddleware, type Money, type PlanFeatureMap, type PlanInterval, type PlanPricing, type PlanRegistry, type PlatformBillingAdapter, type RecurringPricing, type Subscription, type SubscriptionLineItem, type SubscriptionStatus, type UsagePricing, type UsageRecord, type UsageRecordFilter };

package/dist/billing/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Platform-agnostic billing types.
+ *
+ * These types define the billing model used across all platform adapters.
+ * Platform-specific adapters implement the BillingService interface with
+ * their own GraphQL mutations and API calls.
+ */
+/** Billing interval for recurring charges. */
+type PlanInterval = 'EVERY_30_DAYS' | 'ANNUAL';
+/** Subscription status lifecycle values. */
+type SubscriptionStatus = 'PENDING' | 'ACTIVE' | 'CANCELLED' | 'EXPIRED' | 'FROZEN' | 'DECLINED';
+/** Monetary value with currency code. */
+interface Money {
+    amount: string;
+    currencyCode: string;
+}
+/** Pricing configuration for a recurring plan charge. */
+interface RecurringPricing {
+    type: 'recurring';
+    price: Money;
+    interval: PlanInterval;
+}
+/** Pricing configuration for a usage-based charge. */
+interface UsagePricing {
+    type: 'usage';
+    cappedAmount: Money;
+    terms: string;
+}
+/** Union of pricing detail types. */
+type PlanPricing = RecurringPricing | UsagePricing;
+/** A line item within a subscription (one plan can have recurring + usage lines). */
+interface SubscriptionLineItem {
+    id: string;
+    plan: {
+        pricingDetails: PlanPricing;
+    };
+}
+/** Billing plan definition. */
+interface BillingPlan {
+    name: string;
+    description: string;
+    lineItems: PlanPricing[];
+    features: string[];
+    trialDays?: number;
+    isDefault?: boolean;
+    sortOrder?: number;
+}
+/** A subscription record stored in the database. */
+interface Subscription {
+    id: string;
+    shopDomain: string;
+    shopifySubscriptionId: string | null;
+    planName: string;
+    status: SubscriptionStatus;
+    currentPeriodEnd: Date | null;
+    trialEndsAt: Date | null;
+    confirmationUrl: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Input for creating a new subscription. */
+interface CreateSubscriptionInput {
+    shopDomain: string;
+    planName: string;
+    returnUrl: string;
+    trialDays?: number;
+    shopifySubscriptionId?: string;
+    confirmationUrl?: string;
+}
+/** Input for creating a usage record. */
+interface CreateUsageRecordInput {
+    subscriptionId: string;
+    description: string;
+    amount: string;
+    currencyCode?: string;
+    idempotencyKey?: string;
+}
+/** A usage record stored in the database. */
+interface UsageRecord {
+    id: string;
+    subscriptionId: string;
+    description: string;
+    amount: string;
+    currencyCode: string;
+    idempotencyKey: string | null;
+    createdAt: Date;
+}
+/** Filter options for querying usage records. */
+interface UsageRecordFilter {
+    subscriptionId: string;
+    startDate?: Date;
+    endDate?: Date;
+}
+
+/**
+ * Platform-agnostic billing service interface.
+ *
+ * Defines the contract for billing operations that platform adapters
+ * must implement. Core billing service provides the base implementation
+ * with Prisma persistence.
+ */
+
+/** Core billing service for subscription and usage management. */
+interface BillingService {
+    /** Create a new subscription record in the database. */
+    createSubscription(input: CreateSubscriptionInput): Promise<Subscription>;
+    /** Get a subscription by its internal ID. */
+    getSubscription(id: string): Promise<Subscription | null>;
+    /** Get the currently active subscription for a shop. */
+    getActiveSubscription(shopDomain: string): Promise<Subscription | null>;
+    /** List all subscriptions for a shop. */
+    listSubscriptions(shopDomain: string): Promise<Subscription[]>;
+    /** Update subscription status (e.g., from webhook callback). */
+    updateSubscriptionStatus(id: string, status: SubscriptionStatus): Promise<Subscription>;
+    /** Update a subscription by its Shopify subscription ID. */
+    updateSubscriptionByShopifyId(shopifySubscriptionId: string, updates: Partial<Pick<Subscription, 'status' | 'currentPeriodEnd'>>): Promise<Subscription | null>;
+    /** Cancel a subscription. */
+    cancelSubscription(id: string): Promise<Subscription>;
+    /** Create a usage record against a subscription. */
+    createUsageRecord(input: CreateUsageRecordInput): Promise<UsageRecord>;
+    /** Get usage records with optional date range filtering. */
+    getUsageRecords(filter: UsageRecordFilter): Promise<UsageRecord[]>;
+    /** Calculate total usage amount for a subscription within a date range. */
+    calculateTotalUsage(filter: UsageRecordFilter): Promise<string>;
+}
+/** Plan registry for managing available billing plans. */
+interface PlanRegistry {
+    /** Register a billing plan. */
+    register(plan: BillingPlan): void;
+    /** Get a plan by name. */
+    get(name: string): BillingPlan | undefined;
+    /** List all registered plans (sorted by sortOrder). */
+    list(): BillingPlan[];
+    /** Get the default plan (if any). */
+    getDefault(): BillingPlan | undefined;
+}
+/** Platform-specific billing adapter for GraphQL operations. */
+interface PlatformBillingAdapter {
+    /** Create a subscription via the platform's API (e.g., Shopify GraphQL). */
+    createPlatformSubscription(input: {
+        shop: string;
+        accessToken: string;
+        planName: string;
+        lineItems: BillingPlan['lineItems'];
+        returnUrl: string;
+        trialDays?: number;
+    }): Promise<{
+        shopifySubscriptionId: string;
+        confirmationUrl: string;
+    }>;
+    /** Create a usage record via the platform's API. */
+    createPlatformUsageRecord(input: {
+        shop: string;
+        accessToken: string;
+        subscriptionLineItemId: string;
+        amount: string;
+        currencyCode: string;
+        description: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Cancel a subscription via the platform's API. */
+    cancelPlatformSubscription(input: {
+        shop: string;
+        accessToken: string;
+        subscriptionId: string;
+    }): Promise<void>;
+}
+
+/**
+ * Feature gate interfaces for plan-based feature gating.
+ *
+ * Provides a way to restrict features based on the merchant's
+ * active billing plan. Used by route middleware to enforce
+ * plan-level access control.
+ */
+
+/** Maps plan names to the features they include. */
+type PlanFeatureMap = Record<string, string[]>;
+/** Definition of a gated feature. */
+interface FeatureDefinition {
+    name: string;
+    description: string;
+    requiredPlan?: string;
+}
+/** Configuration for the feature gate middleware. */
+interface FeatureGateConfig {
+    /** Map of plan names to their included features. */
+    planFeatures: PlanFeatureMap;
+    /** Function to retrieve the active subscription's plan for a shop. */
+    getPlanForShop: (shopDomain: string) => Promise<BillingPlan | null>;
+    /** Features available to all shops regardless of plan (free tier). */
+    freeFeatures?: string[];
+}
+/** Feature gate middleware for checking plan-based access. */
+interface FeatureGateMiddleware {
+    /** Check if a shop has access to a feature. */
+    hasFeature(shopDomain: string, featureName: string): Promise<boolean>;
+    /** Require a feature — throws FeatureGateError if not available. */
+    requireFeature(shopDomain: string, featureName: string): Promise<void>;
+    /** Get all available features for a shop based on their plan. */
+    getAvailableFeatures(shopDomain: string): Promise<string[]>;
+    /** Get the current plan name for a shop (null if no active subscription). */
+    getCurrentPlanName(shopDomain: string): Promise<string | null>;
+}
+/** Error thrown when a feature is not available for the current plan. */
+declare class FeatureGateError extends Error {
+    readonly featureName: string;
+    readonly currentPlan: string | null;
+    constructor(featureName: string, currentPlan: string | null);
+}
+
+export { type BillingPlan, type BillingService, type CreateSubscriptionInput, type CreateUsageRecordInput, type FeatureDefinition, type FeatureGateConfig, FeatureGateError, type FeatureGateMiddleware, type Money, type PlanFeatureMap, type PlanInterval, type PlanPricing, type PlanRegistry, type PlatformBillingAdapter, type RecurringPricing, type Subscription, type SubscriptionLineItem, type SubscriptionStatus, type UsagePricing, type UsageRecord, type UsageRecordFilter };

package/dist/billing/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/billing/index.ts
+var billing_exports = {};
+__export(billing_exports, {
+  FeatureGateError: () => FeatureGateError
+});
+module.exports = __toCommonJS(billing_exports);
+
+// src/billing/feature-gate.ts
+var FeatureGateError = class extends Error {
+  featureName;
+  currentPlan;
+  constructor(featureName, currentPlan) {
+    const planInfo = currentPlan ? `plan "${currentPlan}"` : "no active plan";
+    super(`Feature "${featureName}" is not available with ${planInfo}`);
+    this.name = "FeatureGateError";
+    this.featureName = featureName;
+    this.currentPlan = currentPlan;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FeatureGateError
+});
+//# sourceMappingURL=index.js.map

package/dist/billing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/billing/index.ts","../../src/billing/feature-gate.ts"],"sourcesContent":["/**\n * @uniforge/platform-core/billing\n *\n * Platform-agnostic billing interfaces for subscription management,\n * usage billing, plan definitions, and feature gating.\n */\n\nexport type {\n  PlanInterval,\n  SubscriptionStatus,\n  Money,\n  RecurringPricing,\n  UsagePricing,\n  PlanPricing,\n  SubscriptionLineItem,\n  BillingPlan,\n  Subscription,\n  CreateSubscriptionInput,\n  CreateUsageRecordInput,\n  UsageRecord,\n  UsageRecordFilter,\n} from './types.js';\n\nexport type {\n  BillingService,\n  PlanRegistry,\n  PlatformBillingAdapter,\n} from './service.js';\n\nexport type {\n  PlanFeatureMap,\n  FeatureDefinition,\n  FeatureGateConfig,\n  FeatureGateMiddleware,\n} from './feature-gate.js';\n\nexport { FeatureGateError } from './feature-gate.js';\n","/**\n * Feature gate interfaces for plan-based feature gating.\n *\n * Provides a way to restrict features based on the merchant's\n * active billing plan. Used by route middleware to enforce\n * plan-level access control.\n */\n\nimport type { BillingPlan } from './types.js';\n\n/** Maps plan names to the features they include. */\nexport type PlanFeatureMap = Record<string, string[]>;\n\n/** Definition of a gated feature. */\nexport interface FeatureDefinition {\n  name: string;\n  description: string;\n  requiredPlan?: string;\n}\n\n/** Configuration for the feature gate middleware. */\nexport interface FeatureGateConfig {\n  /** Map of plan names to their included features. */\n  planFeatures: PlanFeatureMap;\n\n  /** Function to retrieve the active subscription's plan for a shop. */\n  getPlanForShop: (shopDomain: string) => Promise<BillingPlan | null>;\n\n  /** Features available to all shops regardless of plan (free tier). */\n  freeFeatures?: string[];\n}\n\n/** Feature gate middleware for checking plan-based access. */\nexport interface FeatureGateMiddleware {\n  /** Check if a shop has access to a feature. */\n  hasFeature(shopDomain: string, featureName: string): Promise<boolean>;\n\n  /** Require a feature — throws FeatureGateError if not available. */\n  requireFeature(shopDomain: string, featureName: string): Promise<void>;\n\n  /** Get all available features for a shop based on their plan. */\n  getAvailableFeatures(shopDomain: string): Promise<string[]>;\n\n  /** Get the current plan name for a shop (null if no active subscription). */\n  getCurrentPlanName(shopDomain: string): Promise<string | null>;\n}\n\n/** Error thrown when a feature is not available for the current plan. */\nexport class FeatureGateError extends Error {\n  public readonly featureName: string;\n  public readonly currentPlan: string | null;\n\n  constructor(featureName: string, currentPlan: string | null) {\n    const planInfo = currentPlan ? `plan \"${currentPlan}\"` : 'no active plan';\n    super(`Feature \"${featureName}\" is not available with ${planInfo}`);\n    this.name = 'FeatureGateError';\n    this.featureName = featureName;\n    this.currentPlan = currentPlan;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgDO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1B;AAAA,EACA;AAAA,EAEhB,YAAY,aAAqB,aAA4B;AAC3D,UAAM,WAAW,cAAc,SAAS,WAAW,MAAM;AACzD,UAAM,YAAY,WAAW,2BAA2B,QAAQ,EAAE;AAClE,SAAK,OAAO;AACZ,SAAK,cAAc;AACnB,SAAK,cAAc;AAAA,EACrB;AACF;","names":[]}

package/dist/billing/index.mjs

@@ -0,0 +1,16 @@
+// src/billing/feature-gate.ts
+var FeatureGateError = class extends Error {
+  featureName;
+  currentPlan;
+  constructor(featureName, currentPlan) {
+    const planInfo = currentPlan ? `plan "${currentPlan}"` : "no active plan";
+    super(`Feature "${featureName}" is not available with ${planInfo}`);
+    this.name = "FeatureGateError";
+    this.featureName = featureName;
+    this.currentPlan = currentPlan;
+  }
+};
+export {
+  FeatureGateError
+};
+//# sourceMappingURL=index.mjs.map

package/dist/billing/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/billing/feature-gate.ts"],"sourcesContent":["/**\n * Feature gate interfaces for plan-based feature gating.\n *\n * Provides a way to restrict features based on the merchant's\n * active billing plan. Used by route middleware to enforce\n * plan-level access control.\n */\n\nimport type { BillingPlan } from './types.js';\n\n/** Maps plan names to the features they include. */\nexport type PlanFeatureMap = Record<string, string[]>;\n\n/** Definition of a gated feature. */\nexport interface FeatureDefinition {\n  name: string;\n  description: string;\n  requiredPlan?: string;\n}\n\n/** Configuration for the feature gate middleware. */\nexport interface FeatureGateConfig {\n  /** Map of plan names to their included features. */\n  planFeatures: PlanFeatureMap;\n\n  /** Function to retrieve the active subscription's plan for a shop. */\n  getPlanForShop: (shopDomain: string) => Promise<BillingPlan | null>;\n\n  /** Features available to all shops regardless of plan (free tier). */\n  freeFeatures?: string[];\n}\n\n/** Feature gate middleware for checking plan-based access. */\nexport interface FeatureGateMiddleware {\n  /** Check if a shop has access to a feature. */\n  hasFeature(shopDomain: string, featureName: string): Promise<boolean>;\n\n  /** Require a feature — throws FeatureGateError if not available. */\n  requireFeature(shopDomain: string, featureName: string): Promise<void>;\n\n  /** Get all available features for a shop based on their plan. */\n  getAvailableFeatures(shopDomain: string): Promise<string[]>;\n\n  /** Get the current plan name for a shop (null if no active subscription). */\n  getCurrentPlanName(shopDomain: string): Promise<string | null>;\n}\n\n/** Error thrown when a feature is not available for the current plan. */\nexport class FeatureGateError extends Error {\n  public readonly featureName: string;\n  public readonly currentPlan: string | null;\n\n  constructor(featureName: string, currentPlan: string | null) {\n    const planInfo = currentPlan ? `plan \"${currentPlan}\"` : 'no active plan';\n    super(`Feature \"${featureName}\" is not available with ${planInfo}`);\n    this.name = 'FeatureGateError';\n    this.featureName = featureName;\n    this.currentPlan = currentPlan;\n  }\n}\n"],"mappings":";AAgDO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1B;AAAA,EACA;AAAA,EAEhB,YAAY,aAAqB,aAA4B;AAC3D,UAAM,WAAW,cAAc,SAAS,WAAW,MAAM;AACzD,UAAM,YAAY,WAAW,2BAA2B,QAAQ,EAAE;AAClE,SAAK,OAAO;AACZ,SAAK,cAAc;AACnB,SAAK,cAAc;AAAA,EACrB;AACF;","names":[]}

package/dist/graphql/index.d.cts

@@ -0,0 +1,100 @@
+/**
+ * Platform-agnostic GraphQL client types.
+ *
+ * These types define the GraphQL client interface used across all platform adapters.
+ * Platform-specific adapters wrap the base client with features like rate limiting
+ * and caching.
+ */
+/** Platform-agnostic GraphQL client interface. */
+interface GraphQLClient {
+    query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<GraphQLResponse<T>>;
+    mutate<T = unknown>(mutation: string, variables?: Record<string, unknown>): Promise<GraphQLResponse<T>>;
+}
+/** Response from a GraphQL operation. */
+interface GraphQLResponse<T = unknown> {
+    data?: T;
+    errors?: GraphQLError[];
+    extensions?: GraphQLExtensions;
+}
+/** A single GraphQL error. */
+interface GraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/** GraphQL response extensions including query cost information. */
+interface GraphQLExtensions {
+    cost?: QueryCost;
+    [key: string]: unknown;
+}
+/** Shopify query cost information returned in response extensions. */
+interface QueryCost {
+    requestedQueryCost: number;
+    actualQueryCost: number;
+    throttleStatus: ThrottleStatus;
+}
+/** Shopify API throttle status from query cost extensions. */
+interface ThrottleStatus {
+    maximumAvailable: number;
+    currentlyAvailable: number;
+    restoreRate: number;
+}
+/** Configuration for creating a GraphQL client. */
+interface GraphQLClientConfig {
+    shop: string;
+    accessToken: string;
+    apiVersion: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+}
+
+/**
+ * Platform-agnostic rate limiting interfaces for GraphQL clients.
+ *
+ * Supports leaky bucket rate limiting based on Shopify's query cost system.
+ */
+
+/** Rate limiter that controls GraphQL request throughput. */
+interface RateLimiter {
+    acquire(): Promise<void>;
+    getStatus(): RateLimitStatus;
+    updateFromResponse(cost?: QueryCost): void;
+}
+/** Current rate limit status. */
+interface RateLimitStatus {
+    available: number;
+    maximum: number;
+    restoreRate: number;
+}
+/** Configuration for rate limiter creation. */
+interface RateLimitConfig {
+    maxAvailable?: number;
+    restoreRatePerSecond?: number;
+    minimumAvailable?: number;
+}
+
+/**
+ * Platform-agnostic GraphQL caching interfaces.
+ *
+ * Provides a cache layer for GraphQL query results to reduce API calls
+ * and improve response times.
+ */
+/** Cache for GraphQL query results. */
+interface GraphQLCache {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    invalidate(pattern: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Configuration for GraphQL cache creation. */
+interface CacheConfig {
+    enabled?: boolean;
+    defaultTtlSeconds?: number;
+    keyPrefix?: string;
+}
+
+export type { CacheConfig, GraphQLCache, GraphQLClient, GraphQLClientConfig, GraphQLError, GraphQLExtensions, GraphQLResponse, QueryCost, RateLimitConfig, RateLimitStatus, RateLimiter, ThrottleStatus };