@majikah/majik-api 0.1.0 → 0.1.2

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+import { RateLimit, RateLimitFrequency } from "./types";
+export declare const DEFAULT_RATE_LIMIT: RateLimit;
+/**
+ * Hard ceiling for any rate limit set on a MajikAPI key.
+ * No key — regardless of trust level — may exceed this without bypassSafeLimit.
+ * Expressed in req/min for normalisation purposes; stored as a RateLimit for
+ * consistency with the rest of the API.
+ */
+export declare const MAX_RATE_LIMIT: RateLimit;
+/** Multipliers to convert each frequency unit into requests-per-minute. */
+export declare const TO_MINUTES: Record<RateLimitFrequency, number>;

package/dist/constants.js

@@ -0,0 +1,23 @@
+// ─────────────────────────────────────────────
+//  Constants
+// ─────────────────────────────────────────────
+export const DEFAULT_RATE_LIMIT = {
+    amount: 100,
+    frequency: "minutes",
+};
+/**
+ * Hard ceiling for any rate limit set on a MajikAPI key.
+ * No key — regardless of trust level — may exceed this without bypassSafeLimit.
+ * Expressed in req/min for normalisation purposes; stored as a RateLimit for
+ * consistency with the rest of the API.
+ */
+export const MAX_RATE_LIMIT = {
+    amount: 500,
+    frequency: "minutes",
+};
+/** Multipliers to convert each frequency unit into requests-per-minute. */
+export const TO_MINUTES = {
+    seconds: 1 / 60,
+    minutes: 1,
+    hours: 60,
+};

package/dist/majik-api.d.ts

@@ -1,12 +1,4 @@
-import type { DomainWhitelist, IPWhitelist, MajikAPICreateOptions, MajikAPIJSON, MajikAPISettings, RateLimit, RateLimitFrequency } from "./types";
-export declare const DEFAULT_RATE_LIMIT: RateLimit;
-/**
- * Hard ceiling for any rate limit set on a MajikAPI key.
- * No key — regardless of trust level — may exceed this without bypassSafeLimit.
- * Expressed in req/min for normalisation purposes; stored as a RateLimit for
- * consistency with the rest of the API.
- */
-export declare const MAX_RATE_LIMIT: RateLimit;
+import type { DomainWhitelist, IPWhitelist, MajikAPICreateOptions, MajikAPIJSON, MajikAPISettings, Quota, QuotaFrequency, RateLimit, RateLimitFrequency } from "./types";
 export declare class MajikAPI {
     private readonly _id;
     private readonly _owner_id;
@@ -34,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;
     /**
@@ -66,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
@@ -145,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[];
@@ -167,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,108 +1,16 @@
-import { generateID, sha256 } from "./utils";
+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
 // ─────────────────────────────────────────────
-export const DEFAULT_RATE_LIMIT = {
-    amount: 100,
-    frequency: "minutes",
-};
-/**
- * Hard ceiling for any rate limit set on a MajikAPI key.
- * No key — regardless of trust level — may exceed this without bypassSafeLimit.
- * Expressed in req/min for normalisation purposes; stored as a RateLimit for
- * consistency with the rest of the API.
- */
-export const MAX_RATE_LIMIT = {
-    amount: 500,
-    frequency: "minutes",
-};
-/** Multipliers to convert each frequency unit into requests-per-minute. */
-const TO_MINUTES = {
-    seconds: 1 / 60,
-    minutes: 1,
-    hours: 60,
-};
-// ─────────────────────────────────────────────
-//  Validation Helpers
-// ─────────────────────────────────────────────
-function assertString(value, label) {
-    if (typeof value !== "string" || value.trim() === "") {
-        throw new TypeError(`[MajikAPI] "${label}" must be a non-empty string. Received: ${JSON.stringify(value)}`);
-    }
-}
-function assertPositiveInteger(value, label) {
-    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
-        throw new RangeError(`[MajikAPI] "${label}" must be a positive integer. Received: ${JSON.stringify(value)}`);
-    }
-}
-function assertRateLimitFrequency(value, label) {
-    const valid = ["seconds", "minutes", "hours"];
-    if (!valid.includes(value)) {
-        throw new TypeError(`[MajikAPI] "${label}" must be one of: ${valid.join(", ")}. Received: ${JSON.stringify(value)}`);
-    }
-}
-function assertBoolean(value, label) {
-    if (typeof value !== "boolean") {
-        throw new TypeError(`[MajikAPI] "${label}" must be a boolean. Received: ${JSON.stringify(value)}`);
-    }
-}
-function assertStringArray(value, label) {
-    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
-        throw new TypeError(`[MajikAPI] "${label}" must be an array of strings. Received: ${JSON.stringify(value)}`);
-    }
-}
-function isValidIPv4(ip) {
-    return (/^(\d{1,3}\.){3}\d{1,3}$/.test(ip) &&
-        ip.split(".").every((o) => parseInt(o) <= 255));
-}
-function isValidIPv6(ip) {
-    return /^[0-9a-fA-F:]+$/.test(ip) && ip.includes(":");
-}
-function isValidCIDR(cidr) {
-    const [ip, prefix] = cidr.split("/");
-    if (!prefix)
-        return false;
-    const p = parseInt(prefix);
-    return ((isValidIPv4(ip) && p >= 0 && p <= 32) ||
-        (isValidIPv6(ip) && p >= 0 && p <= 128));
-}
-function validateIP(ip) {
-    if (!isValidIPv4(ip) && !isValidIPv6(ip) && !isValidCIDR(ip)) {
-        throw new Error(`[MajikAPI] Invalid IP address or CIDR: "${ip}"`);
-    }
-}
-function isValidDomain(domain) {
-    return (/^(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z]{2,})+$/.test(domain) || /^\*$/.test(domain));
-}
-function validateDomain(domain) {
-    if (!isValidDomain(domain)) {
-        throw new Error(`[MajikAPI] Invalid domain: "${domain}"`);
-    }
-}
-function isValidISODate(value) {
-    const d = new Date(value);
-    return !isNaN(d.getTime());
-}
-// ─────────────────────────────────────────────
-//  Default Settings Factory
-// ─────────────────────────────────────────────
-function buildDefaultSettings(overrides) {
-    return {
-        rateLimit: { ...DEFAULT_RATE_LIMIT, ...(overrides?.rateLimit ?? {}) },
-        ipWhitelist: {
-            enabled: false,
-            addresses: [],
-            ...(overrides?.ipWhitelist ?? {}),
-        },
-        domainWhitelist: {
-            enabled: false,
-            domains: [],
-            ...(overrides?.domainWhitelist ?? {}),
-        },
-        allowedMethods: overrides?.allowedMethods ?? [],
-        metadata: overrides?.metadata ?? {},
-    };
-}
+const VALID_QUOTA_FREQUENCIES = [
+    "hours",
+    "days",
+    "weeks",
+    "months",
+    "quarters",
+    "years",
+];
 // ─────────────────────────────────────────────
 //  MajikAPI Class
 // ─────────────────────────────────────────────
@@ -201,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)) {
@@ -237,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 {
@@ -247,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),
         };
     }
@@ -262,9 +173,6 @@ export class MajikAPI {
         assertString(this._owner_id, "owner_id");
         assertString(this._name, "name");
         assertString(this._api_key, "api_key");
-        if (!/^[a-f0-9]{64}$/.test(this._api_key)) {
-            throw new Error("[MajikAPI] validate(): 'api_key' does not appear to be a valid SHA-256 hash.");
-        }
         if (!(this._timestamp instanceof Date) ||
             isNaN(this._timestamp.getTime())) {
             throw new TypeError("[MajikAPI] validate(): 'timestamp' is not a valid Date.");
@@ -319,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");
@@ -346,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
     // ─────────────────────────────────────────────
     /**
@@ -555,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);
@@ -562,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);
     }
@@ -616,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));
@@ -633,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.d.ts

@@ -1,6 +1,20 @@
+import { MajikAPISettings, RateLimitFrequency } from "./types";
 export declare function sha256(input: string): string;
 export declare function arrayToBase64(data: Uint8Array): string;
 /**
  * Generate a Random v4 UUID
  */
 export declare function generateID(): string;
+export declare function assertString(value: unknown, label: string): asserts value is string;
+export declare function assertPositiveInteger(value: unknown, label: string): asserts value is number;
+export declare function assertRateLimitFrequency(value: unknown, label: string): asserts value is RateLimitFrequency;
+export declare function assertBoolean(value: unknown, label: string): asserts value is boolean;
+export declare function assertStringArray(value: unknown, label: string): asserts value is string[];
+export declare function isValidIPv4(ip: string): boolean;
+export declare function isValidIPv6(ip: string): boolean;
+export declare function isValidCIDR(cidr: string): boolean;
+export declare function validateIP(ip: string): void;
+export declare function isValidDomain(domain: string): boolean;
+export declare function validateDomain(domain: string): void;
+export declare function isValidISODate(value: string): boolean;
+export declare function buildDefaultSettings(overrides?: Partial<MajikAPISettings>): MajikAPISettings;

package/dist/utils.js

@@ -1,5 +1,6 @@
 import { hash } from "@stablelib/sha256";
 import { v4 as uuidv4 } from "uuid";
+import { DEFAULT_RATE_LIMIT } from "./constants";
 export function sha256(input) {
     const hashed = hash(new TextEncoder().encode(input));
     return arrayToBase64(hashed);
@@ -25,3 +26,85 @@ export function generateID() {
         throw new Error(`Failed to generate ID: ${error}`);
     }
 }
+// ─────────────────────────────────────────────
+//  Validation Helpers
+// ─────────────────────────────────────────────
+export function assertString(value, label) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new TypeError(`[MajikAPI] "${label}" must be a non-empty string. Received: ${JSON.stringify(value)}`);
+    }
+}
+export function assertPositiveInteger(value, label) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new RangeError(`[MajikAPI] "${label}" must be a positive integer. Received: ${JSON.stringify(value)}`);
+    }
+}
+export function assertRateLimitFrequency(value, label) {
+    const valid = ["seconds", "minutes", "hours"];
+    if (!valid.includes(value)) {
+        throw new TypeError(`[MajikAPI] "${label}" must be one of: ${valid.join(", ")}. Received: ${JSON.stringify(value)}`);
+    }
+}
+export function assertBoolean(value, label) {
+    if (typeof value !== "boolean") {
+        throw new TypeError(`[MajikAPI] "${label}" must be a boolean. Received: ${JSON.stringify(value)}`);
+    }
+}
+export function assertStringArray(value, label) {
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        throw new TypeError(`[MajikAPI] "${label}" must be an array of strings. Received: ${JSON.stringify(value)}`);
+    }
+}
+export function isValidIPv4(ip) {
+    return (/^(\d{1,3}\.){3}\d{1,3}$/.test(ip) &&
+        ip.split(".").every((o) => parseInt(o) <= 255));
+}
+export function isValidIPv6(ip) {
+    return /^[0-9a-fA-F:]+$/.test(ip) && ip.includes(":");
+}
+export function isValidCIDR(cidr) {
+    const [ip, prefix] = cidr.split("/");
+    if (!prefix)
+        return false;
+    const p = parseInt(prefix);
+    return ((isValidIPv4(ip) && p >= 0 && p <= 32) ||
+        (isValidIPv6(ip) && p >= 0 && p <= 128));
+}
+export function validateIP(ip) {
+    if (!isValidIPv4(ip) && !isValidIPv6(ip) && !isValidCIDR(ip)) {
+        throw new Error(`[MajikAPI] Invalid IP address or CIDR: "${ip}"`);
+    }
+}
+export function isValidDomain(domain) {
+    return (/^(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z]{2,})+$/.test(domain) || /^\*$/.test(domain));
+}
+export function validateDomain(domain) {
+    if (!isValidDomain(domain)) {
+        throw new Error(`[MajikAPI] Invalid domain: "${domain}"`);
+    }
+}
+export function isValidISODate(value) {
+    const d = new Date(value);
+    return !isNaN(d.getTime());
+}
+// ─────────────────────────────────────────────
+//  Default Settings Factory
+// ─────────────────────────────────────────────
+export function buildDefaultSettings(overrides) {
+    return {
+        rateLimit: { ...DEFAULT_RATE_LIMIT, ...(overrides?.rateLimit ?? {}) },
+        ipWhitelist: {
+            enabled: false,
+            addresses: [],
+            ...(overrides?.ipWhitelist ?? {}),
+        },
+        domainWhitelist: {
+            enabled: false,
+            domains: [],
+            ...(overrides?.domainWhitelist ?? {}),
+        },
+        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.0",
+  "version": "0.1.2",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",