owostack 0.1.0

package/dist/index.js

@@ -0,0 +1,727 @@
+// src/catalog.ts
+var _featureRegistry = /* @__PURE__ */ new Map();
+var FeatureMethods = class {
+  static async check(handle, customer, opts) {
+    if (!handle._client) {
+      throw new Error(
+        `Feature '${handle.slug}' is not bound to an Owostack client. Pass it inside a plan() in the catalog option of new Owostack({}).`
+      );
+    }
+    return handle._client.check({
+      customer,
+      feature: handle.slug,
+      ...opts
+    });
+  }
+};
+var BooleanHandle = class {
+  slug;
+  featureType = "boolean";
+  featureName;
+  _client = null;
+  constructor(slug, name) {
+    this.slug = slug;
+    this.featureName = name;
+  }
+  async check(customer, opts) {
+    return FeatureMethods.check(this, customer, opts);
+  }
+  on() {
+    return {
+      _type: "plan_feature",
+      slug: this.slug,
+      featureType: "boolean",
+      name: this.featureName,
+      enabled: true
+    };
+  }
+  off() {
+    return {
+      _type: "plan_feature",
+      slug: this.slug,
+      featureType: "boolean",
+      name: this.featureName,
+      enabled: false
+    };
+  }
+};
+function metered(slug, opts) {
+  const callable = (creditCost) => ({ feature: slug, creditCost });
+  const handleProps = {
+    slug,
+    featureType: "metered",
+    featureName: opts?.name,
+    _client: null,
+    async check(customer, checkOpts) {
+      return FeatureMethods.check(this, customer, checkOpts);
+    },
+    async track(customer, value = 1, trackOpts) {
+      const handle = this;
+      if (!handle._client) {
+        throw new Error(
+          `Feature '${slug}' is not bound to an Owostack client.`
+        );
+      }
+      return handle._client.track({
+        customer,
+        feature: slug,
+        value,
+        ...trackOpts
+      });
+    },
+    limit(value, config) {
+      return {
+        _type: "plan_feature",
+        slug,
+        featureType: "metered",
+        name: opts?.name,
+        enabled: true,
+        config: { limit: value, reset: "monthly", overage: "block", ...config }
+      };
+    },
+    included(value, config) {
+      return this.limit(value, config);
+    },
+    unlimited(config) {
+      return {
+        _type: "plan_feature",
+        slug,
+        featureType: "metered",
+        name: opts?.name,
+        enabled: true,
+        config: { limit: null, reset: "monthly", overage: "block", ...config }
+      };
+    },
+    config(configOpts) {
+      const isEnabled = configOpts.enabled !== false;
+      return {
+        _type: "plan_feature",
+        slug,
+        featureType: "metered",
+        name: opts?.name,
+        enabled: isEnabled,
+        config: { reset: "monthly", overage: "block", ...configOpts }
+      };
+    }
+  };
+  Object.assign(callable, handleProps);
+  _featureRegistry.set(slug, callable);
+  return callable;
+}
+function boolean(slug, opts) {
+  const handle = new BooleanHandle(slug, opts?.name);
+  _featureRegistry.set(slug, handle);
+  return handle;
+}
+var CreditSystemHandle = class {
+  slug;
+  name;
+  description;
+  featureCosts;
+  constructor(slug, featureCosts, opts) {
+    this.slug = slug;
+    this.featureCosts = featureCosts;
+    this.name = opts?.name;
+    this.description = opts?.description;
+  }
+  credits(amount, config) {
+    return {
+      _type: "plan_feature",
+      slug: this.slug,
+      featureType: "metered",
+      name: this.name,
+      enabled: true,
+      config: {
+        limit: amount,
+        reset: config?.reset || "monthly",
+        overage: config?.overage || "block"
+      }
+    };
+  }
+  _buildDefinition() {
+    return {
+      _type: "credit_system",
+      slug: this.slug,
+      name: this.name || this.slug,
+      description: this.description,
+      features: Array.from(this.featureCosts.entries()).map(
+        ([feature, creditCost]) => ({
+          feature,
+          creditCost
+        })
+      )
+    };
+  }
+};
+var _creditSystemRegistry = /* @__PURE__ */ new Map();
+function creditSystem(slug, opts) {
+  const featureCosts = /* @__PURE__ */ new Map();
+  for (const featureEntry of opts.features) {
+    featureCosts.set(featureEntry.feature, featureEntry.creditCost);
+  }
+  const handle = new CreditSystemHandle(slug, featureCosts, {
+    name: opts.name,
+    description: opts.description
+  });
+  _creditSystemRegistry.set(slug, handle);
+  return handle;
+}
+function plan(slug, config) {
+  return {
+    _type: "plan",
+    slug,
+    ...config
+  };
+}
+function slugToName(slug) {
+  return slug.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function buildSyncPayload(catalog, defaultProvider) {
+  const featureMap = /* @__PURE__ */ new Map();
+  for (const entry of catalog) {
+    if (entry._type !== "plan") continue;
+    for (const f of entry.features) {
+      if (_creditSystemRegistry.has(f.slug)) continue;
+      if (!featureMap.has(f.slug)) {
+        featureMap.set(f.slug, {
+          slug: f.slug,
+          type: f.featureType,
+          name: f.name || slugToName(f.slug)
+        });
+      }
+    }
+  }
+  const creditSystems = catalog.filter((e) => e._type === "credit_system").map((cs) => ({
+    slug: cs.slug,
+    name: cs.name,
+    description: cs.description,
+    features: cs.features
+  }));
+  for (const entry of catalog) {
+    if (entry._type !== "plan") continue;
+    for (const f of entry.features) {
+      const csHandle = _creditSystemRegistry.get(f.slug);
+      if (csHandle && !creditSystems.find((cs) => cs.slug === f.slug)) {
+        const def = csHandle._buildDefinition();
+        creditSystems.push({
+          slug: def.slug,
+          name: def.name,
+          description: def.description,
+          features: def.features
+        });
+      }
+    }
+  }
+  const plans = catalog.filter((e) => e._type === "plan").map((p) => ({
+    slug: p.slug,
+    name: p.name,
+    description: p.description ?? void 0,
+    price: p.price,
+    currency: p.currency,
+    interval: p.interval,
+    planGroup: p.planGroup ?? void 0,
+    trialDays: p.trialDays ?? void 0,
+    provider: p.provider ?? void 0,
+    metadata: p.metadata ?? void 0,
+    features: p.features.map((f) => ({
+      slug: f.slug,
+      enabled: f.enabled,
+      // Boolean features have no limit concept (null), metered features use limit from config
+      limit: f.featureType === "boolean" ? null : f.config?.limit ?? null,
+      // Boolean features have no reset interval
+      ...f.featureType !== "boolean" && {
+        reset: f.config?.reset || "monthly"
+      },
+      ...f.config?.overage && { overage: f.config.overage },
+      ...f.config?.overagePrice !== void 0 && {
+        overagePrice: f.config.overagePrice
+      },
+      ...f.config?.maxOverageUnits !== void 0 && {
+        maxOverageUnits: f.config.maxOverageUnits
+      },
+      ...f.config?.billingUnits !== void 0 && {
+        billingUnits: f.config.billingUnits
+      },
+      ...f.config?.creditCost !== void 0 && {
+        creditCost: f.config.creditCost
+      }
+    }))
+  }));
+  return {
+    defaultProvider,
+    features: Array.from(featureMap.values()),
+    creditSystems,
+    plans
+  };
+}
+function bindFeatureHandles(client, catalog) {
+  if (catalog) {
+    const slugsInCatalog = /* @__PURE__ */ new Set();
+    for (const entry of catalog) {
+      if (entry._type === "plan") {
+        for (const f of entry.features) {
+          slugsInCatalog.add(f.slug);
+        }
+      }
+    }
+    for (const [slug, handle] of _featureRegistry) {
+      if (slugsInCatalog.has(slug)) {
+        handle._client = client;
+      }
+    }
+  } else {
+    for (const handle of _featureRegistry.values()) {
+      handle._client = client;
+    }
+  }
+}
+
+// src/index.ts
+var Owostack = class {
+  /** @internal — exposed for CLI tooling */
+  _config;
+  apiUrl;
+  /** Billing: unbilled usage, invoices, and invoice generation */
+  billing;
+  /** Wallet: payment methods — callable + namespace */
+  wallet;
+  constructor(config) {
+    this._config = config;
+    this.apiUrl = this.resolveApiUrl(config);
+    this.billing = new BillingNamespace(this);
+    this.wallet = buildWalletFn(this);
+    this.plans = buildPlansFn(this);
+    if (config.catalog && config.catalog.length > 0) {
+      bindFeatureHandles(this, config.catalog);
+    }
+  }
+  resolveApiUrl(config) {
+    if (config.apiUrl) {
+      return config.apiUrl;
+    }
+    if (config.mode === "sandbox") {
+      return "https://sandbox.owostack.com";
+    }
+    if (config.mode === "live") {
+      return "https://api.owostack.com";
+    }
+    return "https://api.owostack.com";
+  }
+  /**
+   * Override the API key at runtime (used by CLI).
+   * @internal
+   */
+  setSecretKey(key) {
+    this._config.secretKey = key;
+  }
+  /**
+   * Override the API URL at runtime (used by CLI).
+   * @internal
+   */
+  setApiUrl(url) {
+    this._config.apiUrl = url;
+    this.apiUrl = url;
+  }
+  /**
+   * sync() - Push catalog to the API
+   *
+   * Reconciles features and plans defined in the catalog with the server.
+   * Idempotent — safe to call multiple times with the same config.
+   * Only creates/updates; never deletes.
+   *
+   * @example
+   * ```ts
+   * const result = await owo.sync();
+   * console.log(`Created ${result.features.created.length} features`);
+   * ```
+   */
+  async sync() {
+    if (!this._config.catalog || this._config.catalog.length === 0) {
+      return {
+        success: true,
+        features: { created: [], updated: [], unchanged: [] },
+        creditSystems: { created: [], updated: [], unchanged: [] },
+        plans: { created: [], updated: [], unchanged: [] },
+        warnings: ["No catalog entries to sync."]
+      };
+    }
+    const payload = buildSyncPayload(
+      this._config.catalog,
+      this._config.provider
+    );
+    const response = await this.post("/sync", payload);
+    return response;
+  }
+  /**
+   * attach() - Checkout & Subscription Management
+   *
+   * Creates checkout sessions, handles upgrades/downgrades, manages subscriptions.
+   * Auto-creates the customer if customerData is provided and the customer doesn't exist.
+   *
+   * @example
+   * ```ts
+   * const result = await owo.attach({
+   *   customer: 'user_123',
+   *   product: 'pro_plan',
+   *   customerData: { email: 'user@example.com', name: 'Jane' },
+   * });
+   *
+   * // Redirect user to checkout
+   * window.location.href = result.url;
+   * ```
+   */
+  async attach(params) {
+    const response = await this.post("/attach", params);
+    return response;
+  }
+  /**
+   * check() - Feature Gating & Access Control
+   *
+   * Queries whether a customer can access a feature based on their plan,
+   * payment status, and usage limits.
+   *
+   * Pass sendEvent: true to atomically check AND track usage in one call.
+   *
+   * @example
+   * ```ts
+   * const access = await owo.check({
+   *   customer: 'user_123',
+   *   feature: 'api_calls',
+   *   customerData: { email: 'user@example.com' },
+   * });
+   *
+   * if (!access.allowed) {
+   *   throw new Error(access.code);
+   * }
+   * ```
+   */
+  async check(params) {
+    const response = await this.post("/check", params);
+    return response;
+  }
+  /**
+   * track() - Usage Metering & Billing
+   *
+   * Records usage events, decrements quotas, and triggers billing for
+   * pay-as-you-go features.
+   *
+   * @example
+   * ```ts
+   * await owo.track({
+   *   customer: 'user_123',
+   *   feature: 'api_calls',
+   *   value: 1,
+   *   customerData: { email: 'user@example.com' },
+   * });
+   * ```
+   */
+  async track(params) {
+    const response = await this.post("/track", params);
+    return response;
+  }
+  /**
+   * addon() - Purchase Add-on Credit Pack
+   *
+   * Buy additional credits scoped to a credit system.
+   * If the customer has a card on file, charges immediately.
+   * Otherwise returns a checkout URL.
+   *
+   * @example
+   * ```ts
+   * const result = await owo.addon({
+   *   customer: 'user_123',
+   *   pack: '250-credits',
+   *   quantity: 2,
+   * });
+   *
+   * if (result.requiresCheckout) {
+   *   window.location.href = result.checkoutUrl!;
+   * } else {
+   *   console.log(`Balance: ${result.balance} credits`);
+   * }
+   * ```
+   */
+  async addon(params) {
+    const response = await this.post("/addon", params);
+    return response;
+  }
+  /**
+   * customer() - Create or resolve a customer
+   *
+   * Creates a new customer or resolves an existing one by email or ID.
+   * If customerData is provided and customer doesn't exist, creates a new customer.
+   *
+   * @example
+   * ```ts
+   * // Create new customer
+   * const customer = await owo.customer({
+   *   email: 'org@acme.com',
+   *   name: 'Acme Corp',
+   *   metadata: { plan: 'enterprise' }
+   * });
+   *
+   * // Get existing customer
+   * const existing = await owo.customer({ email: 'org@acme.com' });
+   * ```
+   */
+  async customer(params) {
+    const response = await this.post("/customers", params);
+    return response;
+  }
+  /**
+   * addEntity() - Add a feature entity (e.g., seat)
+   *
+   * Creates a new entity scoped to a feature. Validates against the feature limit.
+   * Throws if the limit would be exceeded.
+   *
+   * @example
+   * ```ts
+   * await owo.addEntity({
+   *   customer: 'org@acme.com',
+   *   feature: 'seats',
+   *   entity: 'user_123',
+   *   name: 'John Doe',
+   *   metadata: { role: 'admin' }
+   * });
+   * ```
+   */
+  async addEntity(params) {
+    const response = await this.post("/entities", params);
+    return response;
+  }
+  /**
+   * removeEntity() - Remove a feature entity
+   *
+   * Removes an entity and frees up the slot for the feature limit.
+   *
+   * @example
+   * ```ts
+   * await owo.removeEntity({
+   *   customer: 'org@acme.com',
+   *   feature: 'seats',
+   *   entity: 'user_123'
+   * });
+   * ```
+   */
+  async removeEntity(params) {
+    const response = await this.post("/entities/remove", params);
+    return response;
+  }
+  /**
+   * listEntities() - List feature entities
+   *
+   * Returns all entities for a customer, optionally filtered by feature.
+   *
+   * @example
+   * ```ts
+   * // List all entities
+   * const { entities } = await owo.listEntities({ customer: 'org@acme.com' });
+   *
+   * // List seats only
+   * const { entities: seats } = await owo.listEntities({
+   *   customer: 'org@acme.com',
+   *   feature: 'seats'
+   * });
+   * ```
+   */
+  async listEntities(params) {
+    const query = { customer: params.customer };
+    if (params.feature) query.feature = params.feature;
+    const response = await this.get("/entities", query);
+    return response;
+  }
+  /**
+   * plans() - List Plans
+   *
+   * Returns all active plans for the organization. Useful for building
+   * pricing pages and plan selection UIs.
+   *
+   * @example
+   * ```ts
+   * const { plans } = await owo.plans();
+   * plans.forEach(p => console.log(p.name, p.price));
+   *
+   * // Filter by group
+   * const { plans: support } = await owo.plans({ group: 'support' });
+   *
+   * // Get a single plan by slug
+   * const plan = await owo.plans.get('pro');
+   * ```
+   */
+  plans;
+  /**
+   * Internal POST request handler
+   * @internal
+   */
+  async post(endpoint, body) {
+    const response = await fetch(`${this.apiUrl}${endpoint}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this._config.secretKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const resp = await response.json();
+      const errorData = resp.error || resp;
+      throw new OwostackError(
+        errorData.code || "unknown_error",
+        errorData.message || errorData.error || "Request failed"
+      );
+    }
+    return response.json();
+  }
+  /**
+   * Internal GET request handler
+   * @internal
+   */
+  async get(endpoint, query) {
+    const url = new URL(`${this.apiUrl}${endpoint}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== "")
+          url.searchParams.set(key, value);
+      }
+    }
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this._config.secretKey}`
+      }
+    });
+    if (!response.ok) {
+      const resp = await response.json();
+      const errorData = resp.error || resp;
+      throw new OwostackError(
+        errorData.code || "unknown_error",
+        errorData.message || errorData.error || "Request failed"
+      );
+    }
+    return response.json();
+  }
+};
+function buildPlansFn(client) {
+  const fn = ((params) => {
+    const query = {};
+    if (params?.group) query.group = params.group;
+    if (params?.interval) query.interval = params.interval;
+    if (params?.currency) query.currency = params.currency;
+    if (params?.includeInactive) query.includeInactive = "true";
+    return client.get("/plans", query);
+  });
+  fn.get = async (slug) => {
+    const response = await client.get(`/plans/${encodeURIComponent(slug)}`);
+    return response.plan;
+  };
+  return fn;
+}
+function buildWalletFn(client) {
+  const fn = ((customer) => client.get("/wallet", { customer }));
+  fn.setup = (customer, opts) => client.post("/wallet/setup", {
+    customer,
+    ...opts
+  });
+  fn.list = (customer) => client.get("/wallet", { customer });
+  fn.remove = (customer, id) => client.post("/wallet/remove", {
+    customer,
+    id
+  });
+  return fn;
+}
+var BillingNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * usage() - Get Unbilled Overage Usage
+   *
+   * Returns a breakdown of all billable usage that hasn't been invoiced yet.
+   *
+   * @example
+   * ```ts
+   * const usage = await owo.billing.usage({ customer: 'user_123' });
+   * console.log(`Owes: ${usage.currency} ${usage.totalEstimated / 100}`);
+   * ```
+   */
+  async usage(params) {
+    const response = await this.client.get("/billing/usage", {
+      customer: params.customer
+    });
+    return response;
+  }
+  /**
+   * invoice() - Generate an Invoice
+   *
+   * Creates an invoice for the customer's unbilled overage usage.
+   * Fails if there's no unbilled usage to invoice.
+   *
+   * @example
+   * ```ts
+   * const result = await owo.billing.invoice({ customer: 'user_123' });
+   * console.log(`Invoice ${result.invoice.number}: ${result.invoice.total}`);
+   * ```
+   */
+  async invoice(params) {
+    const response = await this.client.post("/billing/invoice", params);
+    return response;
+  }
+  /**
+   * invoices() - List Past Invoices
+   *
+   * Returns all invoices for a customer.
+   *
+   * @example
+   * ```ts
+   * const result = await owo.billing.invoices({ customer: 'user_123' });
+   * result.invoices.forEach(inv => console.log(inv.number, inv.status));
+   * ```
+   */
+  async invoices(params) {
+    const response = await this.client.get("/billing/invoices", {
+      customer: params.customer
+    });
+    return response;
+  }
+  /**
+   * pay() - Pay an Invoice
+   *
+   * Attempts to auto-charge the customer's saved payment method.
+   * If no card on file or charge fails, returns a checkout URL instead.
+   *
+   * @example
+   * ```ts
+   * const result = await owo.billing.pay({ invoiceId: 'inv_xxx' });
+   * if (!result.paid) {
+   *   // Redirect customer to checkout
+   *   window.location.href = result.checkoutUrl!;
+   * }
+   * ```
+   */
+  async pay(params) {
+    const response = await this.client.post(
+      `/billing/invoice/${encodeURIComponent(params.invoiceId)}/pay`,
+      { callbackUrl: params.callbackUrl }
+    );
+    return response;
+  }
+};
+var OwostackError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "OwostackError";
+    this.code = code;
+  }
+};
+export {
+  BooleanHandle,
+  CreditSystemHandle,
+  Owostack,
+  OwostackError,
+  boolean,
+  buildSyncPayload,
+  creditSystem,
+  metered,
+  plan
+};