@majikah/majik-api 0.1.1 → 0.1.2

package/dist/majik-api.d.ts

@@ -1,4 +1,4 @@
-import type { DomainWhitelist, IPWhitelist, MajikAPICreateOptions, MajikAPIJSON, MajikAPISettings, RateLimit, RateLimitFrequency } from "./types";
+import type { DomainWhitelist, IPWhitelist, MajikAPICreateOptions, MajikAPIJSON, MajikAPISettings, Quota, QuotaFrequency, RateLimit, RateLimitFrequency } from "./types";
 export declare class MajikAPI {
     private readonly _id;
     private readonly _owner_id;
@@ -26,12 +26,14 @@ export declare class MajikAPI {
      * Accepts the raw output of `toJSON()`, a Supabase row, or a Redis cache hit.
      *
      * `raw_api_key` is intentionally NOT restored — it is never in the JSON.
+     * `is_valid` is intentionally NOT restored — it is a computed getter.
      */
     static fromJSON(data: MajikAPIJSON): MajikAPI;
     /**
      * Serialise to a plain JSON-safe object matching MajikAPIJSON.
      * Safe to store in Supabase or cache in Redis.
      * raw_api_key is NEVER included.
+     * is_valid is computed at serialisation time from isActive().
      */
     toJSON(): MajikAPIJSON;
     /**
@@ -58,14 +60,61 @@ export declare class MajikAPI {
      * (500 req/min). Attempting to set a higher rate will throw unless
      * bypassSafeLimit is explicitly passed as true.
      *
-     * @param amount        - Number of allowed requests per frequency window.
-     * @param frequency     - The time window unit.
+     * @param amount          - Number of allowed requests per frequency window.
+     * @param frequency       - The time window unit.
      * @param bypassSafeLimit - When true, skips the MAX_RATE_LIMIT ceiling check.
-     *                        Defaults to false. Use with caution.
+     *                          Defaults to false. Use with caution.
      */
     setRateLimit(amount: number, frequency: RateLimitFrequency, bypassSafeLimit?: boolean): void;
     /** Reset the rate limit back to DEFAULT_RATE_LIMIT. */
     resetRateLimit(): void;
+    /**
+     * Set a fixed lifetime quota for this key.
+     * Once total usage reaches `limit`, isQuotaExceeded() returns true.
+     *
+     * @param limit - Maximum total number of requests allowed. Must be a
+     *                positive integer.
+     *
+     * @example
+     * key.setFixedQuota(10_000); // 10 000 requests total, ever
+     */
+    setFixedQuota(limit: number): void;
+    /**
+     * Set a periodic rolling quota for this key.
+     * Usage is expected to be tracked externally (e.g. in Redis or Supabase)
+     * and passed into isQuotaExceeded() for comparison.
+     *
+     * @param limit     - Maximum number of requests allowed per `frequency` window.
+     * @param frequency - The time window unit.
+     *
+     * @example
+     * key.setPeriodicQuota(50_000, "months"); // 50k requests per month
+     * key.setPeriodicQuota(1_000,  "days");   // 1k requests per day
+     */
+    setPeriodicQuota(limit: number, frequency: QuotaFrequency): void;
+    /**
+     * Remove any quota restriction from this key.
+     * After calling this, isQuotaExceeded() will always return false.
+     */
+    clearQuota(): void;
+    /**
+     * Check whether the given usage count has met or exceeded this key's quota.
+     *
+     * This method does NOT track usage itself — `currentUsage` must be supplied
+     * by the caller from whatever store you use (Redis counter, Supabase
+     * aggregate, etc.).
+     *
+     * For a `fixed` quota, pass the key's all-time request count.
+     * For a `periodic` quota, pass the request count for the current window.
+     *
+     * Returns:
+     *   - `false` if quota is null (unlimited).
+     *   - `true`  if currentUsage >= the configured limit.
+     *   - `false` if currentUsage < the configured limit.
+     *
+     * @param currentUsage - The usage count to check against the quota.
+     */
+    isQuotaExceeded(currentUsage: number): boolean;
     /**
      * Rotate the API key. Generates a new raw key (or accepts a provided one),
      * hashes it, and replaces _api_key. The stable _id and _owner_id are
@@ -137,9 +186,33 @@ export declare class MajikAPI {
     get timestamp(): string;
     get restricted(): boolean;
     get validUntil(): Date | null;
+    /**
+     * Whether this key is valid for use right now.
+     * True when the key is active (not expired, not restricted).
+     *
+     * Note: this does NOT factor in quota — quota is a runtime check that
+     * requires external usage data. Use isQuotaExceeded(currentUsage) for that.
+     */
+    get is_valid(): boolean;
     /** Returns a deep clone — mutations to the returned object have no effect. */
     get settings(): Readonly<MajikAPISettings>;
     get rateLimit(): Readonly<RateLimit>;
+    /**
+     * The current quota configuration.
+     * null means unlimited.
+     * Use isQuotaExceeded(currentUsage) to compare against live usage.
+     */
+    get quota(): Readonly<Quota>;
+    /**
+     * The configured quota limit, or null if no quota is set.
+     * Convenience shorthand for `key.quota?.limit ?? null`.
+     */
+    get quotaLimit(): number | null;
+    /**
+     * The quota frequency if this is a periodic quota, otherwise null.
+     * Useful for determining the reset window without inspecting the full quota object.
+     */
+    get quotaFrequency(): QuotaFrequency | null;
     get ipWhitelist(): Readonly<IPWhitelist>;
     get domainWhitelist(): Readonly<DomainWhitelist>;
     get allowedMethods(): string[];
@@ -159,6 +232,7 @@ export declare class MajikAPI {
      */
     get status(): "active" | "restricted" | "expired" | "revoked";
     private static parseDate;
+    private static assertQuotaFrequency;
     private static validateSettings;
     toString(): string;
 }

package/dist/majik-api.js

@@ -1,6 +1,17 @@
 import { DEFAULT_RATE_LIMIT, MAX_RATE_LIMIT, TO_MINUTES } from "./constants";
 import { assertBoolean, assertPositiveInteger, assertRateLimitFrequency, assertString, assertStringArray, buildDefaultSettings, generateID, isValidISODate, sha256, validateDomain, validateIP, } from "./utils";
 // ─────────────────────────────────────────────
+//  Constants
+// ─────────────────────────────────────────────
+const VALID_QUOTA_FREQUENCIES = [
+    "hours",
+    "days",
+    "weeks",
+    "months",
+    "quarters",
+    "years",
+];
+// ─────────────────────────────────────────────
 //  MajikAPI Class
 // ─────────────────────────────────────────────
 export class MajikAPI {
@@ -98,6 +109,7 @@ export class MajikAPI {
      * Accepts the raw output of `toJSON()`, a Supabase row, or a Redis cache hit.
      *
      * `raw_api_key` is intentionally NOT restored — it is never in the JSON.
+     * `is_valid` is intentionally NOT restored — it is a computed getter.
      */
     static fromJSON(data) {
         if (typeof data !== "object" || data === null || Array.isArray(data)) {
@@ -134,6 +146,7 @@ export class MajikAPI {
      * Serialise to a plain JSON-safe object matching MajikAPIJSON.
      * Safe to store in Supabase or cache in Redis.
      * raw_api_key is NEVER included.
+     * is_valid is computed at serialisation time from isActive().
      */
     toJSON() {
         return {
@@ -144,6 +157,7 @@ export class MajikAPI {
             timestamp: this._timestamp.toISOString(),
             restricted: this._restricted,
             valid_until: this._valid_until ? this._valid_until.toISOString() : null,
+            is_valid: this.is_valid,
             settings: structuredClone(this._settings),
         };
     }
@@ -213,10 +227,10 @@ export class MajikAPI {
      * (500 req/min). Attempting to set a higher rate will throw unless
      * bypassSafeLimit is explicitly passed as true.
      *
-     * @param amount        - Number of allowed requests per frequency window.
-     * @param frequency     - The time window unit.
+     * @param amount          - Number of allowed requests per frequency window.
+     * @param frequency       - The time window unit.
      * @param bypassSafeLimit - When true, skips the MAX_RATE_LIMIT ceiling check.
-     *                        Defaults to false. Use with caution.
+     *                          Defaults to false. Use with caution.
      */
     setRateLimit(amount, frequency, bypassSafeLimit = false) {
         assertPositiveInteger(amount, "amount");
@@ -240,6 +254,70 @@ export class MajikAPI {
         this._settings.rateLimit = { ...DEFAULT_RATE_LIMIT };
     }
     // ─────────────────────────────────────────────
+    //  Quota Management
+    // ─────────────────────────────────────────────
+    /**
+     * Set a fixed lifetime quota for this key.
+     * Once total usage reaches `limit`, isQuotaExceeded() returns true.
+     *
+     * @param limit - Maximum total number of requests allowed. Must be a
+     *                positive integer.
+     *
+     * @example
+     * key.setFixedQuota(10_000); // 10 000 requests total, ever
+     */
+    setFixedQuota(limit) {
+        assertPositiveInteger(limit, "limit");
+        this._settings.quota = { type: "fixed", limit };
+    }
+    /**
+     * Set a periodic rolling quota for this key.
+     * Usage is expected to be tracked externally (e.g. in Redis or Supabase)
+     * and passed into isQuotaExceeded() for comparison.
+     *
+     * @param limit     - Maximum number of requests allowed per `frequency` window.
+     * @param frequency - The time window unit.
+     *
+     * @example
+     * key.setPeriodicQuota(50_000, "months"); // 50k requests per month
+     * key.setPeriodicQuota(1_000,  "days");   // 1k requests per day
+     */
+    setPeriodicQuota(limit, frequency) {
+        assertPositiveInteger(limit, "limit");
+        MajikAPI.assertQuotaFrequency(frequency, "frequency");
+        this._settings.quota = { type: "periodic", limit, frequency };
+    }
+    /**
+     * Remove any quota restriction from this key.
+     * After calling this, isQuotaExceeded() will always return false.
+     */
+    clearQuota() {
+        this._settings.quota = null;
+    }
+    /**
+     * Check whether the given usage count has met or exceeded this key's quota.
+     *
+     * This method does NOT track usage itself — `currentUsage` must be supplied
+     * by the caller from whatever store you use (Redis counter, Supabase
+     * aggregate, etc.).
+     *
+     * For a `fixed` quota, pass the key's all-time request count.
+     * For a `periodic` quota, pass the request count for the current window.
+     *
+     * Returns:
+     *   - `false` if quota is null (unlimited).
+     *   - `true`  if currentUsage >= the configured limit.
+     *   - `false` if currentUsage < the configured limit.
+     *
+     * @param currentUsage - The usage count to check against the quota.
+     */
+    isQuotaExceeded(currentUsage) {
+        if (this._settings.quota === null)
+            return false;
+        assertPositiveInteger(currentUsage, "currentUsage");
+        return currentUsage >= this._settings.quota.limit;
+    }
+    // ─────────────────────────────────────────────
     //  Key Rotation
     // ─────────────────────────────────────────────
     /**
@@ -449,6 +527,16 @@ export class MajikAPI {
     get validUntil() {
         return this._valid_until ? new Date(this._valid_until) : null;
     }
+    /**
+     * Whether this key is valid for use right now.
+     * True when the key is active (not expired, not restricted).
+     *
+     * Note: this does NOT factor in quota — quota is a runtime check that
+     * requires external usage data. Use isQuotaExceeded(currentUsage) for that.
+     */
+    get is_valid() {
+        return this.isActive();
+    }
     /** Returns a deep clone — mutations to the returned object have no effect. */
     get settings() {
         return structuredClone(this._settings);
@@ -456,6 +544,31 @@ export class MajikAPI {
     get rateLimit() {
         return { ...this._settings.rateLimit };
     }
+    /**
+     * The current quota configuration.
+     * null means unlimited.
+     * Use isQuotaExceeded(currentUsage) to compare against live usage.
+     */
+    get quota() {
+        return this._settings.quota ? structuredClone(this._settings.quota) : null;
+    }
+    /**
+     * The configured quota limit, or null if no quota is set.
+     * Convenience shorthand for `key.quota?.limit ?? null`.
+     */
+    get quotaLimit() {
+        return this._settings.quota?.limit ?? null;
+    }
+    /**
+     * The quota frequency if this is a periodic quota, otherwise null.
+     * Useful for determining the reset window without inspecting the full quota object.
+     */
+    get quotaFrequency() {
+        if (this._settings.quota?.type === "periodic") {
+            return this._settings.quota.frequency;
+        }
+        return null;
+    }
     get ipWhitelist() {
         return structuredClone(this._settings.ipWhitelist);
     }
@@ -510,12 +623,33 @@ export class MajikAPI {
         }
         throw new TypeError(`[MajikAPI] "${label}" must be a Date instance or an ISO date string.`);
     }
+    static assertQuotaFrequency(value, label) {
+        if (!VALID_QUOTA_FREQUENCIES.includes(value)) {
+            throw new TypeError(`[MajikAPI] "${label}" must be one of: ${VALID_QUOTA_FREQUENCIES.join(", ")}. Got: "${value}"`);
+        }
+    }
     static validateSettings(settings) {
         if (typeof settings !== "object" || settings === null) {
             throw new TypeError("[MajikAPI] 'settings' must be an object.");
         }
         assertPositiveInteger(settings.rateLimit?.amount, "settings.rateLimit.amount");
         assertRateLimitFrequency(settings.rateLimit?.frequency, "settings.rateLimit.frequency");
+        // Validate quota if present
+        if (settings.quota !== null && settings.quota !== undefined) {
+            if (typeof settings.quota !== "object") {
+                throw new TypeError("[MajikAPI] 'settings.quota' must be an object or null.");
+            }
+            assertPositiveInteger(settings.quota.limit, "settings.quota.limit");
+            if (settings.quota.type === "fixed") {
+                // no extra fields to validate
+            }
+            else if (settings.quota.type === "periodic") {
+                MajikAPI.assertQuotaFrequency(settings.quota.frequency, "settings.quota.frequency");
+            }
+            else {
+                throw new TypeError(`[MajikAPI] 'settings.quota.type' must be "fixed" or "periodic". Got: "${settings.quota.type}"`);
+            }
+        }
         assertBoolean(settings.ipWhitelist?.enabled, "settings.ipWhitelist.enabled");
         assertStringArray(settings.ipWhitelist?.addresses, "settings.ipWhitelist.addresses");
         settings.ipWhitelist.addresses.forEach((ip) => validateIP(ip));
@@ -527,7 +661,7 @@ export class MajikAPI {
     //  Debug
     // ─────────────────────────────────────────────
     toString() {
-        return `[MajikAPI id="${this._id}" owner="${this._owner_id}" name="${this._name}" status="${this.status}"]`;
+        return `[MajikAPI id="${this._id}" owner="${this._owner_id}" name="${this._name}" status="${this.status}" is_valid=${this.is_valid}]`;
     }
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toString();

package/dist/types.d.ts

@@ -1,8 +1,29 @@
 export type RateLimitFrequency = "seconds" | "minutes" | "hours";
+export type QuotaFrequency = "hours" | "days" | "weeks" | "months" | "quarters" | "years";
 export interface RateLimit {
     amount: number;
     frequency: RateLimitFrequency;
 }
+/**
+ * Quota controls how many total requests (or requests within a rolling window)
+ * are permitted for this key.
+ *
+ * - `fixed`    — A lifetime cap. Once `limit` total requests have been made,
+ *                the key is considered at quota. No time window applies.
+ *
+ * - `periodic` — A rolling/periodic cap. Resets every `frequency` window
+ *                (e.g. 1 000 requests per day, 50 000 per month).
+ *
+ * - `null`     — No quota. Unlimited usage (subject only to rate limiting).
+ */
+export type Quota = {
+    type: "fixed";
+    limit: number;
+} | {
+    type: "periodic";
+    limit: number;
+    frequency: QuotaFrequency;
+} | null;
 export interface IPWhitelist {
     enabled: boolean;
     addresses: string[];
@@ -13,6 +34,7 @@ export interface DomainWhitelist {
 }
 export interface MajikAPISettings {
     rateLimit: RateLimit;
+    quota: Quota;
     ipWhitelist: IPWhitelist;
     domainWhitelist: DomainWhitelist;
     allowedMethods?: string[];
@@ -27,6 +49,9 @@ export interface MajikAPISettings {
  * api_key  — SHA-256 hash of the raw plaintext key. Has a UNIQUE INDEX in
  *            Postgres (not the PK). Used as the Redis cache key prefix.
  *            The raw key is never stored anywhere.
+ * is_valid — Computed convenience flag. True when the key is active (not
+ *            expired, not restricted). Does NOT account for quota — use
+ *            isQuotaExceeded() for runtime quota checks.
  */
 export interface MajikAPIJSON {
     id: string;
@@ -36,6 +61,7 @@ export interface MajikAPIJSON {
     timestamp: string;
     restricted: boolean;
     valid_until: string | null;
+    is_valid: boolean;
     settings: MajikAPISettings;
 }
 export interface MajikAPICreateOptions {

package/dist/utils.js

@@ -105,5 +105,6 @@ export function buildDefaultSettings(overrides) {
         },
         allowedMethods: overrides?.allowedMethods ?? [],
         metadata: overrides?.metadata ?? {},
+        quota: overrides?.quota ?? null,
     };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-api",
   "type": "module",
   "description": "A high-security API key management library for TypeScript. Handles generation, SHA-256 hashing, and lifecycle management including rate limiting, IP/domain whitelisting, and secure key rotation.",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",