@authhero/adapter-interfaces 4.7.0 → 4.8.0

package/dist/types/adapters/Analytics.d.ts

@@ -1,4 +1,4 @@
-import { AnalyticsQueryParams, AnalyticsQueryResponse, AnalyticsResource, SessionRetentionParams, SessionRetentionResponse } from "../types/Analytics";
+import { AnalyticsQueryParams, AnalyticsQueryResponse, AnalyticsResource, RefreshTokenRetentionParams, RefreshTokenRetentionResponse, SessionRetentionParams, SessionRetentionResponse } from "../types/Analytics";
 export interface AnalyticsAdapter {
     /**
      * Run an analytics query for a tenant. The adapter is responsible for
@@ -13,4 +13,13 @@ export interface AnalyticsAdapter {
      * route responds 501 when it is absent.
      */
     sessionRetention?(tenantId: string, params: SessionRetentionParams): Promise<SessionRetentionResponse>;
+    /**
+     * Weekly refresh-token cohort retention, computed from the refresh_tokens
+     * table. Rotating tokens mint a new row per exchange, so rows are grouped
+     * into rotation families before folding: a family's cohort week comes from
+     * its first token's created_at_ts and its last-active week from the max of
+     * last_exchanged_at_ts/created_at_ts across the family. Optional for the
+     * same reason as sessionRetention.
+     */
+    refreshTokenRetention?(tenantId: string, params: RefreshTokenRetentionParams): Promise<RefreshTokenRetentionResponse>;
 }

package/dist/types/types/Analytics.d.ts

@@ -96,6 +96,36 @@ export interface SessionRetentionResponse {
     to: string;
     cohorts: SessionRetentionCohort[];
 }
+export interface RefreshTokenRetentionParams {
+    /** Number of weekly cohorts to include, counting back from the current week */
+    weeks: number;
+    /** Optional filter to one or more client IDs */
+    client_id?: string[];
+}
+export interface RefreshTokenRetentionCohort {
+    /** ISO date (UTC Monday) the cohort week starts on */
+    cohort: string;
+    /**
+     * Refresh-token families created during the cohort week. Rotating tokens
+     * mint a new row on every exchange, so the retention unit is the rotation
+     * family (a non-rotating token is a family of one).
+     */
+    tokens: number;
+    /**
+     * active[k] = token families still active k weeks after the cohort week,
+     * i.e. last exchanged during week k or later. active[0] === tokens. The
+     * array is truncated at the current week.
+     */
+    active: number[];
+}
+export interface RefreshTokenRetentionResponse {
+    interval: "week";
+    /** Inclusive lower bound of the first cohort week */
+    from: string;
+    /** Timestamp the query ran at; the last cohort week is still in progress */
+    to: string;
+    cohorts: RefreshTokenRetentionCohort[];
+}
 export declare const sessionRetentionCohortSchema: z.ZodObject<{
     cohort: z.ZodString;
     sessions: z.ZodNumber;
@@ -111,6 +141,21 @@ export declare const sessionRetentionResponseSchema: z.ZodObject<{
         active: z.ZodArray<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+export declare const refreshTokenRetentionCohortSchema: z.ZodObject<{
+    cohort: z.ZodString;
+    tokens: z.ZodNumber;
+    active: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const refreshTokenRetentionResponseSchema: z.ZodObject<{
+    interval: z.ZodLiteral<"week">;
+    from: z.ZodString;
+    to: z.ZodString;
+    cohorts: z.ZodArray<z.ZodObject<{
+        cohort: z.ZodString;
+        tokens: z.ZodNumber;
+        active: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const analyticsColumnMetaSchema: z.ZodObject<{
     name: z.ZodString;
     type: z.ZodString;

package/dist/types/utils/session-retention.d.ts

@@ -1,4 +1,4 @@
-import { SessionRetentionResponse } from "../types/Analytics";
+import { RefreshTokenRetentionResponse, SessionRetentionResponse } from "../types/Analytics";
 export declare const WEEK_MS: number;
 /**
  * The Unix epoch (1970-01-01) was a Thursday; adding 3 days before dividing
@@ -30,3 +30,9 @@ export interface SessionRetentionRawRow {
  * enough to reconstruct the whole retention triangle.
  */
 export declare function buildSessionRetention(rows: SessionRetentionRawRow[], weeks: number, now?: number): SessionRetentionResponse;
+/**
+ * Same fold as {@link buildSessionRetention}, but the rows count refresh-token
+ * families (created-week = the family's first token, used-week = its last
+ * exchange) and the per-cohort total is reported as `tokens`.
+ */
+export declare function buildRefreshTokenRetention(rows: SessionRetentionRawRow[], weeks: number, now?: number): RefreshTokenRetentionResponse;

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "4.7.0",
+  "version": "4.8.0",
   "files": [
     "dist"
   ],