@sudobility/ratelimit_service 1.0.1

package/dist/types/responses.d.ts

@@ -0,0 +1,85 @@
+import type { RateLimits } from "./rate-limits";
+/**
+ * Remaining rate limit information for each time period.
+ * undefined means unlimited for that period.
+ */
+export interface RateLimitRemaining {
+    /** Remaining requests this hour. undefined if unlimited */
+    hourly?: number;
+    /** Remaining requests this day. undefined if unlimited */
+    daily?: number;
+    /** Remaining requests this month. undefined if unlimited */
+    monthly?: number;
+}
+/**
+ * Which rate limit period was exceeded.
+ */
+export type ExceededLimit = "hourly" | "daily" | "monthly";
+/**
+ * Result from checking rate limits.
+ */
+export interface RateLimitCheckResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** HTTP status code: 200 if allowed, 429 if rate limited */
+    statusCode: 200 | 429;
+    /** Remaining requests for each time period */
+    remaining: RateLimitRemaining;
+    /** Which limit was exceeded (only set if allowed is false) */
+    exceededLimit?: ExceededLimit;
+    /** Current limits applied to this user */
+    limits: RateLimits;
+}
+/**
+ * Database row type for rate limit counter.
+ * This matches the new schema with history tracking.
+ */
+export interface RateLimitCounterRow {
+    id: string;
+    user_id: string;
+    period_type: string;
+    period_start: Date;
+    request_count: number;
+    created_at: Date | null;
+    updated_at: Date | null;
+}
+/**
+ * Valid period types for rate limiting.
+ */
+export declare enum PeriodType {
+    HOURLY = "hourly",
+    DAILY = "daily",
+    MONTHLY = "monthly"
+}
+/**
+ * A single history entry for a time period.
+ */
+export interface UsageHistoryEntry {
+    /** Start of the time period */
+    period_start: Date;
+    /** End of the time period (exclusive) */
+    period_end: Date;
+    /** Number of requests in this period */
+    request_count: number;
+}
+/**
+ * Usage history for a user and period type.
+ */
+export interface UsageHistory {
+    /** User identifier */
+    user_id: string;
+    /** Type of period: 'hourly', 'daily', or 'monthly' */
+    period_type: PeriodType;
+    /** Historical entries, sorted by period_start descending (most recent first) */
+    entries: UsageHistoryEntry[];
+}
+/**
+ * Subscription information from RevenueCat.
+ */
+export interface SubscriptionInfo {
+    /** Active entitlement names */
+    entitlements: string[];
+    /** Subscription start date (earliest active entitlement's purchase_date) */
+    subscriptionStartedAt: Date | null;
+}
+//# sourceMappingURL=responses.d.ts.map

package/dist/types/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/types/responses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC;IACtB,8CAA8C;IAC9C,SAAS,EAAE,kBAAkB,CAAC;IAC9B,8DAA8D;IAC9D,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,0CAA0C;IAC1C,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,IAAI,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,oBAAY,UAAU;IACpB,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,YAAY,EAAE,IAAI,CAAC;IACnB,yCAAyC;IACzC,UAAU,EAAE,IAAI,CAAC;IACjB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,EAAE,UAAU,CAAC;IACxB,gFAAgF;IAChF,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,4EAA4E;IAC5E,qBAAqB,EAAE,IAAI,GAAG,IAAI,CAAC;CACpC"}

package/dist/types/responses.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PeriodType = void 0;
+/**
+ * Valid period types for rate limiting.
+ */
+var PeriodType;
+(function (PeriodType) {
+    PeriodType["HOURLY"] = "hourly";
+    PeriodType["DAILY"] = "daily";
+    PeriodType["MONTHLY"] = "monthly";
+})(PeriodType || (exports.PeriodType = PeriodType = {}));
+//# sourceMappingURL=responses.js.map

package/dist/types/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../src/types/responses.ts"],"names":[],"mappings":";;;AAkDA;;GAEG;AACH,IAAY,UAIX;AAJD,WAAY,UAAU;IACpB,+BAAiB,CAAA;IACjB,6BAAe,CAAA;IACf,iCAAmB,CAAA;AACrB,CAAC,EAJW,UAAU,0BAAV,UAAU,QAIrB"}

package/dist/utils/time.cjs

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Time utilities for rate limit period calculation.
+ *
+ * All periods are calculated in UTC:
+ * - Hourly: top of hour (e.g., 10:00:00Z, 11:00:00Z)
+ * - Daily: midnight UTC (e.g., 2025-01-15T00:00:00Z)
+ * - Monthly: based on subscription start date
+ *   (e.g., if subscription started 3/5, months are 3/5-4/4, 4/5-5/4, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentHourStart = getCurrentHourStart;
+exports.getNextHourStart = getNextHourStart;
+exports.getNextHourReset = getNextHourReset;
+exports.getCurrentDayStart = getCurrentDayStart;
+exports.getNextDayStart = getNextDayStart;
+exports.getNextDayReset = getNextDayReset;
+exports.getSubscriptionMonthStart = getSubscriptionMonthStart;
+exports.getNextSubscriptionMonthStart = getNextSubscriptionMonthStart;
+exports.getNextMonthReset = getNextMonthReset;
+exports.getTimeUntilReset = getTimeUntilReset;
+// ============================================================================
+// Hourly Period Functions
+// ============================================================================
+/**
+ * Get the start of the current hour in UTC.
+ * @example 14:35:22Z → 14:00:00Z
+ */
+function getCurrentHourStart(now = new Date()) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), now.getUTCHours(), 0, 0, 0));
+}
+/**
+ * Get the start of the next hour in UTC.
+ * @example 14:35:22Z → 15:00:00Z
+ */
+function getNextHourStart(now = new Date()) {
+    const next = new Date(getCurrentHourStart(now));
+    next.setUTCHours(next.getUTCHours() + 1);
+    return next;
+}
+/**
+ * Get the next hour reset timestamp.
+ * @deprecated Use getNextHourStart instead
+ */
+function getNextHourReset(now = new Date()) {
+    return getNextHourStart(now);
+}
+// ============================================================================
+// Daily Period Functions
+// ============================================================================
+/**
+ * Get the start of the current day in UTC (midnight).
+ * @example 2025-01-15T14:35:22Z → 2025-01-15T00:00:00Z
+ */
+function getCurrentDayStart(now = new Date()) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), 0, 0, 0, 0));
+}
+/**
+ * Get the start of the next day in UTC (midnight).
+ * @example 2025-01-15T14:35:22Z → 2025-01-16T00:00:00Z
+ */
+function getNextDayStart(now = new Date()) {
+    const next = new Date(getCurrentDayStart(now));
+    next.setUTCDate(next.getUTCDate() + 1);
+    return next;
+}
+/**
+ * Get the next day reset timestamp.
+ * @deprecated Use getNextDayStart instead
+ */
+function getNextDayReset(now = new Date()) {
+    return getNextDayStart(now);
+}
+// ============================================================================
+// Monthly Period Functions (Subscription-based)
+// ============================================================================
+/**
+ * Get the start of the current subscription month.
+ *
+ * Subscription months are based on the subscription start date:
+ * - If subscription started on day 5, months are: 3/5-4/4, 4/5-5/4, etc.
+ * - If subscription started on day 31 but current month has fewer days,
+ *   uses the last day of the month.
+ *
+ * @param subscriptionStartedAt - When the subscription started (null for no subscription)
+ * @param now - Current date (defaults to now)
+ * @returns Start of the current subscription month
+ *
+ * @example
+ * // Subscription started March 5, current date April 10
+ * getSubscriptionMonthStart(new Date('2025-03-05'), new Date('2025-04-10'))
+ * // Returns: 2025-04-05T00:00:00Z
+ *
+ * @example
+ * // Subscription started March 5, current date April 3
+ * getSubscriptionMonthStart(new Date('2025-03-05'), new Date('2025-04-03'))
+ * // Returns: 2025-03-05T00:00:00Z
+ */
+function getSubscriptionMonthStart(subscriptionStartedAt, now = new Date()) {
+    // If no subscription, fall back to first of current calendar month
+    if (!subscriptionStartedAt) {
+        return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1, 0, 0, 0, 0));
+    }
+    const startDay = subscriptionStartedAt.getUTCDate();
+    const nowYear = now.getUTCFullYear();
+    const nowMonth = now.getUTCMonth();
+    const nowDay = now.getUTCDate();
+    // Get the last day of the current month
+    const lastDayOfMonth = new Date(Date.UTC(nowYear, nowMonth + 1, 0)).getUTCDate();
+    // Adjust start day if it's greater than days in current month
+    const effectiveStartDay = Math.min(startDay, lastDayOfMonth);
+    // Check if we're past the subscription day in this month
+    if (nowDay >= effectiveStartDay) {
+        // Current period started this month
+        return new Date(Date.UTC(nowYear, nowMonth, effectiveStartDay, 0, 0, 0, 0));
+    }
+    else {
+        // Current period started last month
+        const prevMonth = nowMonth === 0 ? 11 : nowMonth - 1;
+        const prevYear = nowMonth === 0 ? nowYear - 1 : nowYear;
+        // Get last day of previous month to handle day overflow
+        const lastDayOfPrevMonth = new Date(Date.UTC(prevYear, prevMonth + 1, 0)).getUTCDate();
+        const effectivePrevStartDay = Math.min(startDay, lastDayOfPrevMonth);
+        return new Date(Date.UTC(prevYear, prevMonth, effectivePrevStartDay, 0, 0, 0, 0));
+    }
+}
+/**
+ * Get the start of the next subscription month.
+ *
+ * @param subscriptionStartedAt - When the subscription started (null for no subscription)
+ * @param now - Current date (defaults to now)
+ * @returns Start of the next subscription month
+ */
+function getNextSubscriptionMonthStart(subscriptionStartedAt, now = new Date()) {
+    const currentMonthStart = getSubscriptionMonthStart(subscriptionStartedAt, now);
+    // If no subscription, use first of next calendar month
+    if (!subscriptionStartedAt) {
+        return new Date(Date.UTC(currentMonthStart.getUTCFullYear(), currentMonthStart.getUTCMonth() + 1, 1, 0, 0, 0, 0));
+    }
+    const startDay = subscriptionStartedAt.getUTCDate();
+    const nextMonth = currentMonthStart.getUTCMonth() + 1;
+    const nextYear = nextMonth > 11
+        ? currentMonthStart.getUTCFullYear() + 1
+        : currentMonthStart.getUTCFullYear();
+    const normalizedMonth = nextMonth % 12;
+    // Get last day of next month to handle day overflow
+    const lastDayOfNextMonth = new Date(Date.UTC(nextYear, normalizedMonth + 1, 0)).getUTCDate();
+    const effectiveStartDay = Math.min(startDay, lastDayOfNextMonth);
+    return new Date(Date.UTC(nextYear, normalizedMonth, effectiveStartDay, 0, 0, 0, 0));
+}
+/**
+ * Get the next month reset timestamp (calendar month).
+ * @deprecated Use getNextSubscriptionMonthStart for subscription-based months
+ */
+function getNextMonthReset(now = new Date()) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0));
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Get time until reset in human-readable format.
+ */
+function getTimeUntilReset(resetAt, now = new Date()) {
+    const diffMs = resetAt.getTime() - now.getTime();
+    if (diffMs <= 0)
+        return "now";
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days}d ${hours % 24}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes % 60}m`;
+    if (minutes > 0)
+        return `${minutes}m`;
+    return `${seconds}s`;
+}
+//# sourceMappingURL=time.js.map

package/dist/utils/time.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Time utilities for rate limit period calculation.
+ *
+ * All periods are calculated in UTC:
+ * - Hourly: top of hour (e.g., 10:00:00Z, 11:00:00Z)
+ * - Daily: midnight UTC (e.g., 2025-01-15T00:00:00Z)
+ * - Monthly: based on subscription start date
+ *   (e.g., if subscription started 3/5, months are 3/5-4/4, 4/5-5/4, etc.)
+ */
+/**
+ * Get the start of the current hour in UTC.
+ * @example 14:35:22Z → 14:00:00Z
+ */
+export declare function getCurrentHourStart(now?: Date): Date;
+/**
+ * Get the start of the next hour in UTC.
+ * @example 14:35:22Z → 15:00:00Z
+ */
+export declare function getNextHourStart(now?: Date): Date;
+/**
+ * Get the next hour reset timestamp.
+ * @deprecated Use getNextHourStart instead
+ */
+export declare function getNextHourReset(now?: Date): Date;
+/**
+ * Get the start of the current day in UTC (midnight).
+ * @example 2025-01-15T14:35:22Z → 2025-01-15T00:00:00Z
+ */
+export declare function getCurrentDayStart(now?: Date): Date;
+/**
+ * Get the start of the next day in UTC (midnight).
+ * @example 2025-01-15T14:35:22Z → 2025-01-16T00:00:00Z
+ */
+export declare function getNextDayStart(now?: Date): Date;
+/**
+ * Get the next day reset timestamp.
+ * @deprecated Use getNextDayStart instead
+ */
+export declare function getNextDayReset(now?: Date): Date;
+/**
+ * Get the start of the current subscription month.
+ *
+ * Subscription months are based on the subscription start date:
+ * - If subscription started on day 5, months are: 3/5-4/4, 4/5-5/4, etc.
+ * - If subscription started on day 31 but current month has fewer days,
+ *   uses the last day of the month.
+ *
+ * @param subscriptionStartedAt - When the subscription started (null for no subscription)
+ * @param now - Current date (defaults to now)
+ * @returns Start of the current subscription month
+ *
+ * @example
+ * // Subscription started March 5, current date April 10
+ * getSubscriptionMonthStart(new Date('2025-03-05'), new Date('2025-04-10'))
+ * // Returns: 2025-04-05T00:00:00Z
+ *
+ * @example
+ * // Subscription started March 5, current date April 3
+ * getSubscriptionMonthStart(new Date('2025-03-05'), new Date('2025-04-03'))
+ * // Returns: 2025-03-05T00:00:00Z
+ */
+export declare function getSubscriptionMonthStart(subscriptionStartedAt: Date | null, now?: Date): Date;
+/**
+ * Get the start of the next subscription month.
+ *
+ * @param subscriptionStartedAt - When the subscription started (null for no subscription)
+ * @param now - Current date (defaults to now)
+ * @returns Start of the next subscription month
+ */
+export declare function getNextSubscriptionMonthStart(subscriptionStartedAt: Date | null, now?: Date): Date;
+/**
+ * Get the next month reset timestamp (calendar month).
+ * @deprecated Use getNextSubscriptionMonthStart for subscription-based months
+ */
+export declare function getNextMonthReset(now?: Date): Date;
+/**
+ * Get time until reset in human-readable format.
+ */
+export declare function getTimeUntilReset(resetAt: Date, now?: Date): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/utils/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAYhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAI7D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAE7D;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAY/D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAI5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAE5D;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,qBAAqB,EAAE,IAAI,GAAG,IAAI,EAClC,GAAG,GAAE,IAAiB,GACrB,IAAI,CAwCN;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,qBAAqB,EAAE,IAAI,GAAG,IAAI,EAClC,GAAG,GAAE,IAAiB,GACrB,IAAI,CAsCN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAI9D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,IAAI,EACb,GAAG,GAAE,IAAiB,GACrB,MAAM,CAcR"}

package/dist/utils/time.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Time utilities for rate limit period calculation.
+ *
+ * All periods are calculated in UTC:
+ * - Hourly: top of hour (e.g., 10:00:00Z, 11:00:00Z)
+ * - Daily: midnight UTC (e.g., 2025-01-15T00:00:00Z)
+ * - Monthly: based on subscription start date
+ *   (e.g., if subscription started 3/5, months are 3/5-4/4, 4/5-5/4, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentHourStart = getCurrentHourStart;
+exports.getNextHourStart = getNextHourStart;
+exports.getNextHourReset = getNextHourReset;
+exports.getCurrentDayStart = getCurrentDayStart;
+exports.getNextDayStart = getNextDayStart;
+exports.getNextDayReset = getNextDayReset;
+exports.getSubscriptionMonthStart = getSubscriptionMonthStart;
+exports.getNextSubscriptionMonthStart = getNextSubscriptionMonthStart;
+exports.getNextMonthReset = getNextMonthReset;
+exports.getTimeUntilReset = getTimeUntilReset;
+// ============================================================================
+// Hourly Period Functions
+// ============================================================================
+/**
+ * Get the start of the current hour in UTC.
+ * @example 14:35:22Z → 14:00:00Z
+ */
+function getCurrentHourStart(now = new Date()) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), now.getUTCHours(), 0, 0, 0));
+}
+/**
+ * Get the start of the next hour in UTC.
+ * @example 14:35:22Z → 15:00:00Z
+ */
+function getNextHourStart(now = new Date()) {
+    const next = new Date(getCurrentHourStart(now));
+    next.setUTCHours(next.getUTCHours() + 1);
+    return next;
+}
+/**
+ * Get the next hour reset timestamp.
+ * @deprecated Use getNextHourStart instead
+ */
+function getNextHourReset(now = new Date()) {
+    return getNextHourStart(now);
+}
+// ============================================================================
+// Daily Period Functions
+// ============================================================================
+/**
+ * Get the start of the current day in UTC (midnight).
+ * @example 2025-01-15T14:35:22Z → 2025-01-15T00:00:00Z
+ */
+function getCurrentDayStart(now = new Date()) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), 0, 0, 0, 0));
+}
+/**
+ * Get the start of the next day in UTC (midnight).
+ * @example 2025-01-15T14:35:22Z → 2025-01-16T00:00:00Z
+ */
+function getNextDayStart(now = new Date()) {
+    const next = new Date(getCurrentDayStart(now));
+    next.setUTCDate(next.getUTCDate() + 1);
+    return next;
+}
+/**
+ * Get the next day reset timestamp.
+ * @deprecated Use getNextDayStart instead
+ */
+function getNextDayReset(now = new Date()) {
+    return getNextDayStart(now);
+}
+// ============================================================================
+// Monthly Period Functions (Subscription-based)
+// ============================================================================
+/**
+ * Get the start of the current subscription month.
+ *
+ * Subscription months are based on the subscription start date:
+ * - If subscription started on day 5, months are: 3/5-4/4, 4/5-5/4, etc.
+ * - If subscription started on day 31 but current month has fewer days,
+ *   uses the last day of the month.
+ *
+ * @param subscriptionStartedAt - When the subscription started (null for no subscription)
+ * @param now - Current date (defaults to now)
+ * @returns Start of the current subscription month
+ *
+ * @example
+ * // Subscription started March 5, current date April 10
+ * getSubscriptionMonthStart(new Date('2025-03-05'), new Date('2025-04-10'))
+ * // Returns: 2025-04-05T00:00:00Z
+ *
+ * @example
+ * // Subscription started March 5, current date April 3
+ * getSubscriptionMonthStart(new Date('2025-03-05'), new Date('2025-04-03'))
+ * // Returns: 2025-03-05T00:00:00Z
+ */
+function getSubscriptionMonthStart(subscriptionStartedAt, now = new Date()) {
+    // If no subscription, fall back to first of current calendar month
+    if (!subscriptionStartedAt) {
+        return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1, 0, 0, 0, 0));
+    }
+    const startDay = subscriptionStartedAt.getUTCDate();
+    const nowYear = now.getUTCFullYear();
+    const nowMonth = now.getUTCMonth();
+    const nowDay = now.getUTCDate();
+    // Get the last day of the current month
+    const lastDayOfMonth = new Date(Date.UTC(nowYear, nowMonth + 1, 0)).getUTCDate();
+    // Adjust start day if it's greater than days in current month
+    const effectiveStartDay = Math.min(startDay, lastDayOfMonth);
+    // Check if we're past the subscription day in this month
+    if (nowDay >= effectiveStartDay) {
+        // Current period started this month
+        return new Date(Date.UTC(nowYear, nowMonth, effectiveStartDay, 0, 0, 0, 0));
+    }
+    else {
+        // Current period started last month
+        const prevMonth = nowMonth === 0 ? 11 : nowMonth - 1;
+        const prevYear = nowMonth === 0 ? nowYear - 1 : nowYear;
+        // Get last day of previous month to handle day overflow
+        const lastDayOfPrevMonth = new Date(Date.UTC(prevYear, prevMonth + 1, 0)).getUTCDate();
+        const effectivePrevStartDay = Math.min(startDay, lastDayOfPrevMonth);
+        return new Date(Date.UTC(prevYear, prevMonth, effectivePrevStartDay, 0, 0, 0, 0));
+    }
+}
+/**
+ * Get the start of the next subscription month.
+ *
+ * @param subscriptionStartedAt - When the subscription started (null for no subscription)
+ * @param now - Current date (defaults to now)
+ * @returns Start of the next subscription month
+ */
+function getNextSubscriptionMonthStart(subscriptionStartedAt, now = new Date()) {
+    const currentMonthStart = getSubscriptionMonthStart(subscriptionStartedAt, now);
+    // If no subscription, use first of next calendar month
+    if (!subscriptionStartedAt) {
+        return new Date(Date.UTC(currentMonthStart.getUTCFullYear(), currentMonthStart.getUTCMonth() + 1, 1, 0, 0, 0, 0));
+    }
+    const startDay = subscriptionStartedAt.getUTCDate();
+    const nextMonth = currentMonthStart.getUTCMonth() + 1;
+    const nextYear = nextMonth > 11
+        ? currentMonthStart.getUTCFullYear() + 1
+        : currentMonthStart.getUTCFullYear();
+    const normalizedMonth = nextMonth % 12;
+    // Get last day of next month to handle day overflow
+    const lastDayOfNextMonth = new Date(Date.UTC(nextYear, normalizedMonth + 1, 0)).getUTCDate();
+    const effectiveStartDay = Math.min(startDay, lastDayOfNextMonth);
+    return new Date(Date.UTC(nextYear, normalizedMonth, effectiveStartDay, 0, 0, 0, 0));
+}
+/**
+ * Get the next month reset timestamp (calendar month).
+ * @deprecated Use getNextSubscriptionMonthStart for subscription-based months
+ */
+function getNextMonthReset(now = new Date()) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0));
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Get time until reset in human-readable format.
+ */
+function getTimeUntilReset(resetAt, now = new Date()) {
+    const diffMs = resetAt.getTime() - now.getTime();
+    if (diffMs <= 0)
+        return "now";
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days}d ${hours % 24}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes % 60}m`;
+    if (minutes > 0)
+        return `${minutes}m`;
+    return `${seconds}s`;
+}
+//# sourceMappingURL=time.js.map

package/dist/utils/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@sudobility/ratelimit_service",
+  "version": "1.0.1",
+  "description": "Shared rate limiting library based on RevenueCat entitlements",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./middleware/hono": {
+      "import": "./dist/middleware/hono.js",
+      "require": "./dist/middleware/hono.cjs",
+      "types": "./dist/middleware/hono.d.ts"
+    },
+    "./schema": {
+      "import": "./dist/schema/rate-limits.js",
+      "require": "./dist/schema/rate-limits.cjs",
+      "types": "./dist/schema/rate-limits.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun run build:esm && bun run build:cjs",
+    "build:esm": "bunx tsc -p tsconfig.esm.json",
+    "build:cjs": "bunx tsc -p tsconfig.cjs.json && bun run build:cjs-rename",
+    "build:cjs-rename": "find dist -name '*.js' -not -name '*.cjs' -exec sh -c 'cp \"$1\" \"${1%.js}.cjs\"' _ {} \\;",
+    "clean": "rm -rf dist",
+    "dev": "bunx tsc --watch",
+    "test": "bun test",
+    "test:run": "bun test",
+    "lint": "bunx eslint src/",
+    "lint:fix": "bunx eslint src/ --fix",
+    "typecheck": "bunx tsc --noEmit",
+    "format": "bunx prettier --write \"src/**/*.ts\"",
+    "format:check": "bunx prettier --check \"src/**/*.ts\"",
+    "verify": "bun run typecheck && bun run lint && bun run test && bun run build",
+    "prepublishOnly": "bun run clean && bun run verify"
+  },
+  "files": [
+    "dist/**/*",
+    "CLAUDE.md"
+  ],
+  "keywords": [
+    "rate-limiting",
+    "revenuecat",
+    "subscription",
+    "entitlements",
+    "hono",
+    "drizzle"
+  ],
+  "author": "Sudobility",
+  "license": "MIT",
+  "peerDependencies": {
+    "@sudobility/types": "^1.9.37",
+    "drizzle-orm": "^0.45.0",
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "@sudobility/types": "^1.9.37",
+    "@types/bun": "latest",
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "drizzle-orm": "^0.45.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "hono": "^4.10.7",
+    "postgres": "^3.4.7",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}