grm-shared-library 1.1.246 → 1.1.247

package/dist/types/modules/user/interfaces/account-analytics.d.ts

@@ -61,7 +61,7 @@ export interface AccountAnalyticsKindRow {
 /** Of the accounts created in the period, how far each got - as they stand now. */
 export interface AccountAnalyticsFunnel {
     created: number;
-    /** Confirmed their phone or e-mail with a one-time code. */
+    /** Proved their phone or e-mail: a sign-in code, Google or Apple (the older app: its one-time code). */
     verified: number;
     acceptedTerms: number;
     /** Signed in at least once. */
@@ -84,7 +84,7 @@ export interface AccountAnalyticsAccounts {
     /** Active accounts that were created in an earlier period. */
     returning: number;
     funnel: AccountAnalyticsFunnel;
-    /** Now: never confirmed their phone or e-mail with a one-time code. */
+    /** Now: never proved their phone or e-mail (see `AccountAnalyticsFunnel.verified`). */
     pendingNow: number;
     /** Now: never signed in. */
     neverSignedIn: number;
@@ -104,12 +104,16 @@ export interface AccountAnalyticsAccounts {
     recency: AccountAnalyticsCount<AccountRecencyBand>[];
 }
 /**
- * How somebody signed in:
- *  - PASSWORD  e-mail and password (the admin and the web);
- *  - OTP       phone number and a one-time code (the app);
- *  - REVIEWER  the app-store reviewers' account.
+ * How somebody signed in - or, for a sign-up, made their account:
+ *  - PASSWORD    e-mail and password (the admin and the web);
+ *  - OTP         the older app (before 1.0.18): phone number and one code sent by SMS and e-mail together;
+ *  - PHONE_CODE  a code to the phone by SMS or a call, or a WhatsApp message from it - proves the number;
+ *  - EMAIL_CODE  a code to the e-mail - proves the e-mail only;
+ *  - GOOGLE      Google vouches for the e-mail;
+ *  - APPLE       Apple vouches for the e-mail (possibly a private relay address);
+ *  - REVIEWER    the app-store reviewers' account.
  */
-export type AccountSignInMethod = 'PASSWORD' | 'OTP' | 'REVIEWER';
+export type AccountSignInMethod = 'PASSWORD' | 'OTP' | 'PHONE_CODE' | 'EMAIL_CODE' | 'GOOGLE' | 'APPLE' | 'REVIEWER';
 export interface AccountAnalyticsMethodRow {
     method: string;
     succeeded: number;
@@ -127,8 +131,13 @@ export interface AccountAnalyticsSignIns {
     firstSignIns: number;
     /** Failed for an e-mail or a code that matches no account (counted, never stored). */
     unknownAccount: number;
+    /**
+     * By AccountSignInMethod. A wrong phone or e-mail code is not a failed sign-in - it is
+     * counted with the codes (`AccountAnalyticsVerificationCodes`) - so PHONE_CODE and
+     * EMAIL_CODE fail only for a switched-off account.
+     */
     byMethod: AccountAnalyticsMethodRow[];
-    /** INVALID_CREDENTIALS, UNVERIFIED, UNKNOWN_ACCOUNT, INVALID_TOKEN, ERROR... */
+    /** INVALID_CREDENTIALS, UNVERIFIED, UNKNOWN_ACCOUNT, INVALID_TOKEN, INVALID_ID_TOKEN, DISABLED, EMAIL_IN_USE, EMAIL_REQUIRED, ERROR... */
     failureReasons: AccountAnalyticsCount[];
     averageDailyUsers: number;
     peakDailyUsers: number;
@@ -141,6 +150,11 @@ export interface AccountAnalyticsOtpActionRow {
     sent: number;
     verified: number;
 }
+/**
+ * The older app's one-time codes (before 1.0.18): one code to the e-mail and the phone
+ * together, for signing up, in and confirming. The current app's codes are in
+ * `AccountAnalyticsSignInOptions.codes`.
+ */
 export interface AccountAnalyticsOtp {
     /** First sends and resends. */
     sent: number;
@@ -237,6 +251,166 @@ export interface AccountAnalyticsPrevious {
     deletionRequests: number;
     guardianLinks: number;
 }
+/** How a code travels. SMS and VOICE carry it to the phone; WHATSAPP is the person messaging us FROM the phone; EMAIL. */
+export type AccountVerificationChannel = 'SMS' | 'VOICE' | 'WHATSAPP' | 'EMAIL';
+/** What a code is for: signing in (or up), or proving the phone number of an account already signed in. */
+export type AccountVerificationPurpose = 'SIGN_IN' | 'VERIFY_PHONE';
+/** One channel's codes for one purpose, in the period. */
+export interface AccountAnalyticsCodeChannelRow {
+    purpose: AccountVerificationPurpose | string;
+    channel: AccountVerificationChannel | string;
+    /** Codes sent - for WhatsApp, the message the person was asked to send us. */
+    sent: number;
+    /** Refused before anything was sent: asked for too often, a number already on another account, a channel that cannot reach it. */
+    refused: number;
+    /** The SMS or call provider could not take it. The app offers the other channels. */
+    notDelivered: number;
+    confirmed: number;
+    wrongCode: number;
+    expired: number;
+    /** WhatsApp: the message came from a number other than the one being proven. */
+    wrongNumber: number;
+    /** confirmed / sent; null with none sent. */
+    confirmationRate: number | null;
+}
+/** Codes by the country of the number (or of the app, for an e-mail code) and channel, in the period. */
+export interface AccountAnalyticsCodeCountryRow {
+    /** KE, UG, TZ - or UNKNOWN. */
+    country: string;
+    channel: AccountVerificationChannel | string;
+    sent: number;
+    notDelivered: number;
+    confirmed: number;
+}
+/** The current app's codes (1.0.18 on): to the phone only, or to the e-mail only - never both. */
+export interface AccountAnalyticsVerificationCodes {
+    sent: number;
+    refused: number;
+    notDelivered: number;
+    confirmed: number;
+    wrongCode: number;
+    expired: number;
+    wrongNumber: number;
+    confirmationRate: number | null;
+    /** Biggest first. */
+    byChannel: AccountAnalyticsCodeChannelRow[];
+    byCountry: AccountAnalyticsCodeCountryRow[];
+    /** Why codes were refused: RATE_LIMITED, PHONE_IN_USE, CHANNEL_UNAVAILABLE. */
+    refusals: AccountAnalyticsCount[];
+}
+/** App users making their own account, in the period. */
+export interface AccountAnalyticsSignUps {
+    /** A phone or e-mail code confirmed that matched no account: the app showed the short sign-up form. */
+    formsStarted: number;
+    /** Accounts made from that form. Google and Apple make the account straight away, with no form. */
+    formsCompleted: number;
+    /** formsCompleted / formsStarted; null with none started. */
+    completionRate: number | null;
+    /** Sign-ups refused - the e-mail or number already has an account, the form came back too late. */
+    refused: number;
+    /** EMAIL_IN_USE, PHONE_IN_USE, EMAIL_REQUIRED, REGISTRATION_EXPIRED. */
+    failureReasons: AccountAnalyticsCount[];
+    /**
+     * App (Mobile-User) accounts created in the period, by how: PHONE_CODE, EMAIL_CODE,
+     * GOOGLE, APPLE, OTP (the older app) - and OTHER: made for the person (a corporate
+     * member, a partner's caller) or before sign-ups were recorded.
+     */
+    byMethod: AccountAnalyticsCount[];
+}
+export interface AccountAnalyticsPhoneCountryRow {
+    country: string;
+    appUsers: number;
+    verified: number;
+    unverified: number;
+    noNumber: number;
+}
+/**
+ * App users' phone numbers - the number a responder calls - as they stand now. A number
+ * is verified only when a code to it, or a WhatsApp message from it, proved it; a number
+ * saved with "Verify later" is shown to the dispatcher as not verified.
+ */
+export interface AccountAnalyticsPhoneNumbers {
+    appUsers: number;
+    withNumber: number;
+    verified: number;
+    unverified: number;
+    noNumber: number;
+    /** verified / appUsers; null with none. */
+    verifiedRate: number | null;
+    /**
+     * Every app user once: how the number was proven - SMS, VOICE, WHATSAPP, LEGACY_OTP (the
+     * older app's code, counted where its SMS always arrived) - or UNVERIFIED, or NONE.
+     */
+    byState: AccountAnalyticsCount[];
+    byCountry: AccountAnalyticsPhoneCountryRow[];
+    /** In the period: numbers proven by somebody already signed in (after Google, Apple or an e-mail code), by channel. */
+    verifiedInPeriod: AccountAnalyticsCount[];
+    /** In the period: "Verify later" - a number saved without proving it. */
+    deferred: number;
+    /** Now: app users whose e-mail is proven (an e-mail code, Google or Apple). */
+    emailVerified: number;
+}
+/** Google or Apple. */
+export interface AccountAnalyticsProviderRow {
+    provider: 'GOOGLE' | 'APPLE' | string;
+    /** Accounts linked to it now. */
+    linkedAccounts: number;
+    /** In the period. */
+    signIns: number;
+    /** Accounts it created, in the period. */
+    newAccounts: number;
+    /** Linked to an account that already had the same proven e-mail, in the period. */
+    linkedExisting: number;
+    /** The provider's token did not check out, or the account could not be used (switched off, e-mail taken or missing). */
+    failed: number;
+}
+/** Sign-ins in one country by one way in, in the period. */
+export interface AccountAnalyticsMethodCountryRow {
+    /** The account's country (KE, UG, TZ), or UNKNOWN. */
+    country: string;
+    method: AccountSignInMethod | string;
+    signIns: number;
+}
+export interface AccountAnalyticsSignInOptionsPoint {
+    /** As `AccountAnalyticsPoint.bucket`. */
+    bucket: string;
+    /** Successful sign-ins in the bucket by AccountSignInMethod; methods with none are left out. */
+    byMethod: Record<string, number>;
+    /** The current app's codes. */
+    codesSent: number;
+    codesConfirmed: number;
+}
+/** The same figures for the previous period of the same length. */
+export interface AccountAnalyticsSignInOptionsPrevious {
+    /** Sign-ins by PHONE_CODE, EMAIL_CODE, GOOGLE or APPLE. */
+    currentAppSignIns: number;
+    /** Sign-ins by the older app's code (OTP). */
+    olderAppSignIns: number;
+    codesSent: number;
+    codesConfirmed: number;
+    phonesVerified: number;
+    deferred: number;
+    formsCompleted: number;
+}
+/**
+ * The ways into the app since 1.0.18 - a code to the phone (SMS, a call, WhatsApp), a code
+ * to the e-mail, Google, Apple - next to the older app's SMS-and-e-mail code, and whether
+ * the phone numbers responders call are proven.
+ */
+export interface AccountAnalyticsSignInOptions {
+    /** People who signed in during the period, each by the way they signed in LAST. */
+    lastMethodUsed: AccountAnalyticsCount[];
+    byCountry: AccountAnalyticsMethodCountryRow[];
+    /** One point per bucket, as `AccountAnalytics.timeline`. */
+    timeline: AccountAnalyticsSignInOptionsPoint[];
+    codes: AccountAnalyticsVerificationCodes;
+    signUps: AccountAnalyticsSignUps;
+    phones: AccountAnalyticsPhoneNumbers;
+    /** GOOGLE and APPLE, always both. */
+    providers: AccountAnalyticsProviderRow[];
+    /** Absent for "forever". */
+    previous: AccountAnalyticsSignInOptionsPrevious | null;
+}
 /** A Super-Admin's view of every organization: one row each, biggest first. */
 export interface AccountAnalyticsOrganizationRow {
     organizationId: number;
@@ -266,6 +440,8 @@ export interface AccountAnalytics {
     passwords: AccountAnalyticsPasswords;
     guardians: AccountAnalyticsGuardians;
     deletions: AccountAnalyticsDeletions;
+    /** The ways into the app, codes by channel and proven phone numbers. Absent only from a clarion-authentication older than this field. */
+    signInOptions?: AccountAnalyticsSignInOptions;
     /** A Super-Admin looking at every organization only. */
     byOrganization?: AccountAnalyticsOrganizationRow[];
 }

package/package.json

@@ -1,72 +1,72 @@
-{
-  "name": "grm-shared-library",
-  "version": "1.1.246",
-  "main": "dist/cjs/index.js",
-  "module": "dist/esm/index.js",
-  "types": "dist/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js"
-    },
-    "./dist/modules/*": {
-      "types": "./dist/types/modules/*.d.ts",
-      "import": "./dist/esm/modules/*.js",
-      "require": "./dist/cjs/modules/*.js"
-    }
-  },
-  "files": [
-    "dist/**/*"
-  ],
-  "scripts": {
-    "clean": "rimraf dist dist-test",
-    "build:cjs": "tsc -p tsconfig.cjs.json",
-    "build:esm": "tsc -p tsconfig.esm.json",
-    "build:types": "tsc -p tsconfig.types.json",
-    "build": "npm run clean && npm run build:types && npm run build:cjs && npm run build:esm",
-    "prepublishOnly": "npm run build",
-    "pretest": "rimraf dist-test",
-    "test": "tsc -p tsconfig.spec.json && node --test \"dist-test/**/*.spec.js\""
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.3",
-    "@types/geojson": "^7946.0.14",
-    "@types/node": "^22.10.5",
-    "rimraf": "^5.0.5",
-    "typescript": "^5.7.3"
-  },
-  "dependencies": {
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/mapped-types": "^2.0.6",
-    "@nestjs/microservices": "^11.0.0",
-    "@nestjs/swagger": "^11.2.0",
-    "@sentry/node": "^8.0.0",
-    "class-transformer": "^0.5.0",
-    "class-validator": "^0.14.0",
-    "express": "^5.1.0",
-    "geojson": "^0.5.0",
-    "grm-shared-library": "^1.1.101",
-    "libphonenumber-js": "^1.13.8",
-    "rxjs": "^7.8.2",
-    "swagger-ui-express": "^5.0.1",
-    "@nestjs/config": "^4.0.0"
-  },
-  "peerDependencies": {
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/microservices": "^11.0.0",
-    "@sentry/node": "^8.0.0",
-    "class-transformer": "^0.5.0",
-    "class-validator": "^0.14.0",
-    "@nestjs/config": "^4.0.0"
-  }
-}
+{
+  "name": "grm-shared-library",
+  "version": "1.1.247",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./dist/modules/*": {
+      "types": "./dist/types/modules/*.d.ts",
+      "import": "./dist/esm/modules/*.js",
+      "require": "./dist/cjs/modules/*.js"
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "clean": "rimraf dist dist-test",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build": "npm run clean && npm run build:types && npm run build:cjs && npm run build:esm",
+    "prepublishOnly": "npm run build",
+    "pretest": "rimraf dist-test",
+    "test": "tsc -p tsconfig.spec.json && node --test \"dist-test/**/*.spec.js\""
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "@types/geojson": "^7946.0.14",
+    "@types/node": "^22.10.5",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/mapped-types": "^2.0.6",
+    "@nestjs/microservices": "^11.0.0",
+    "@nestjs/swagger": "^11.2.0",
+    "@sentry/node": "^8.0.0",
+    "class-transformer": "^0.5.0",
+    "class-validator": "^0.14.0",
+    "express": "^5.1.0",
+    "geojson": "^0.5.0",
+    "grm-shared-library": "^1.1.101",
+    "libphonenumber-js": "^1.13.8",
+    "rxjs": "^7.8.2",
+    "swagger-ui-express": "^5.0.1",
+    "@nestjs/config": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/microservices": "^11.0.0",
+    "@sentry/node": "^8.0.0",
+    "class-transformer": "^0.5.0",
+    "class-validator": "^0.14.0",
+    "@nestjs/config": "^4.0.0"
+  }
+}