@proveanything/smartlinks 1.15.11 → 1.15.13

package/dist/openapi.yaml

@@ -8077,7 +8077,7 @@ paths:
     get:
       tags:
         - authKit
-      summary: authKit.load
+      summary: Revoke a single trusted device by id (authenticated).
       operationId: authKit_load
       security: []
       parameters:
@@ -8970,6 +8970,285 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/UpsertContactRequest"
+  /authkit/{clientId}/mfa/challenge/recovery-code:
+    post:
+      tags:
+        - authKit
+      summary: Finalize a challenged login using a single-use recovery code instead of a sent code (public).
+      operationId: authKit_mfaRecoveryCode
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaFinalizeResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/challenge/send:
+    post:
+      tags:
+        - authKit
+      summary: Send (or resend) an MFA challenge code to the given factor (public).
+      operationId: authKit_mfaChallengeSend
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaChallengeSendResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: string
+              enum:
+                - email
+                - sms
+  /authkit/{clientId}/mfa/challenge/verify:
+    post:
+      tags:
+        - authKit
+      summary: Verify an MFA challenge code and finalize the login (public).
+      operationId: authKit_mfaChallengeVerify
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaFinalizeResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors:
+    get:
+      tags:
+        - authKit
+      summary: List enrolled factors and recovery-code count for the current user (authenticated).
+      operationId: authKit_getMfaFactors
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaFactorsResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/email/confirm:
+    post:
+      tags:
+        - authKit
+      summary: "Confirm email-factor enrollment with the code sent by {@link enrollEmailMfa} (authenticated)."
+      operationId: authKit_confirmEmailMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrolledResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/email/enroll:
+    post:
+      tags:
+        - authKit
+      summary: "Begin email-factor enrollment; sends a code to the account's existing email (authenticated)."
+      operationId: authKit_enrollEmailMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrollSendResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/sms/confirm:
+    post:
+      tags:
+        - authKit
+      summary: "Confirm SMS-factor enrollment with the code sent by {@link enrollSmsMfa} (authenticated)."
+      operationId: authKit_confirmSmsMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrolledResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/sms/enroll:
+    post:
+      tags:
+        - authKit
+      summary: Begin SMS-factor enrollment; sends a code to the given phone number (authenticated).
+      operationId: authKit_enrollSmsMfa
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MfaEnrollSendResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/factors/{factor}:
+    get:
+      tags:
+        - authKit
+      summary: Remove an enrolled MFA factor (authenticated).
+      operationId: authKit_removeMfaFactor
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: factor
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SuccessResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /authkit/{clientId}/mfa/trusted-devices/{id}:
+    delete:
+      tags:
+        - authKit
+      summary: Revoke a single trusted device by id (authenticated).
+      operationId: authKit_revokeTrustedDevice
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SuccessResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /platform/location:
     post:
       tags:
@@ -14979,6 +15258,8 @@ components:
           type: boolean
         location:
           $ref: "#/components/schemas/AnalyticsLocation"
+        source:
+          type: string
         metadata:
           type: object
           additionalProperties: true
@@ -15014,6 +15295,8 @@ components:
           $ref: "#/components/schemas/AnalyticsLocation"
         isAdmin:
           type: boolean
+        redirectMode:
+          type: string
         metadata:
           type: object
           additionalProperties: true
@@ -15222,6 +15505,16 @@ components:
           type: boolean
         hasLocation:
           type: boolean
+        sources:
+          type: array
+          items:
+            type: string
+        redirectMode:
+          type: string
+        redirectModes:
+          type: array
+          items:
+            type: string
     AnalyticsSummaryRequest:
       type: object
       properties:
@@ -18416,6 +18709,124 @@ components:
         userInfo:
           type: object
           additionalProperties: true
+    MfaRequiredDetails:
+      type: object
+      properties:
+        mfaSessionToken:
+          type: string
+        availableFactors:
+          type: array
+          items:
+            type: string
+            enum:
+              - email
+              - sms
+        preferredFactor:
+          type: string
+          enum:
+            - email
+            - sms
+        maskedDestinations:
+          type: object
+          additionalProperties: true
+      required:
+        - mfaSessionToken
+        - availableFactors
+        - preferredFactor
+        - maskedDestinations
+    MfaChallengeSendResponse:
+      type: object
+      properties:
+        success:
+          type: object
+          additionalProperties: true
+        factor:
+          type: string
+          enum:
+            - email
+            - sms
+        destination:
+          type: string
+        expiresAt:
+          type: string
+      required:
+        - success
+        - factor
+        - destination
+        - expiresAt
+    MfaFinalizeResponse:
+      type: object
+      properties:
+        trustedDeviceToken:
+          type: string
+        trustedDeviceExpiresAt:
+          type: string
+    MfaEnrollSendResponse:
+      type: object
+      properties:
+        mfaSessionToken:
+          type: string
+        destination:
+          type: string
+        expiresAt:
+          type: string
+      required:
+        - mfaSessionToken
+        - destination
+        - expiresAt
+    MfaEnrolledResponse:
+      type: object
+      properties:
+        enrolled:
+          type: object
+          additionalProperties: true
+        factor:
+          type: string
+          enum:
+            - email
+            - sms
+      required:
+        - enrolled
+        - factor
+    MfaFactorsResponse:
+      type: object
+      properties:
+        enrolledFactors:
+          type: object
+          additionalProperties: true
+        email:
+          type: object
+          additionalProperties: true
+        sms:
+          type: object
+          additionalProperties: true
+        recoveryCodesRemaining:
+          type: number
+        mfaEnabledForClient:
+          type: boolean
+      required:
+        - enrolledFactors
+        - recoveryCodesRemaining
+        - mfaEnabledForClient
+    TrustedDevice:
+      type: object
+      properties:
+        id:
+          type: string
+        label:
+          type: string
+        createdAtMs:
+          type: number
+        lastUsedAtMs:
+          type: number
+        expiresAtMs:
+          type: number
+      required:
+        - id
+        - label
+        - createdAtMs
+        - lastUsedAtMs
+        - expiresAtMs
     MagicLinkSendResponse:
       type: object
       properties:

package/dist/types/analytics.d.ts

@@ -5,6 +5,13 @@
  * analytics, click tracking, and tag scan analytics for collection dashboards.
  */
 export type AnalyticsSource = 'events' | 'tag';
+/**
+ * Includes `scan_redirect` - logged automatically by the server (not the
+ * client) at the moment a GS1 digital-link scan, claim short-link scan, or
+ * NFC tap decides on a redirect destination, before the client ever loads
+ * anything. Distinct from `scan_tag`, which the client still writes on
+ * landing exactly as before.
+ */
 export type AnalyticsEventType = string;
 export type AnalyticsGranularity = 'hour' | 'day' | 'week' | 'month';
 export type AnalyticsMetric = 'count' | 'uniqueSessions' | 'uniqueVisitors';
@@ -59,6 +66,12 @@ export interface CollectionAnalyticsEvent extends AnalyticsStandardEventFields {
     path?: string;
     isExternal?: boolean;
     location?: AnalyticsLocation;
+    /**
+     * Free-form identifier for which client app logged the event, e.g.
+     * `'portal'`, `'hub'`. No enum/whitelist - send whatever string identifies
+     * your app. Web-events only; not recorded on tag events.
+     */
+    source?: string;
     metadata?: Record<string, any>;
 }
 export interface TagAnalyticsEvent extends AnalyticsStandardEventFields {
@@ -75,6 +88,13 @@ export interface TagAnalyticsEvent extends AnalyticsStandardEventFields {
     path?: string;
     location?: AnalyticsLocation;
     isAdmin?: boolean;
+    /**
+     * Only relevant if you're logging a redirect-style event yourself. In
+     * practice this is mostly written by the server automatically at the
+     * moment a GS1 digital-link scan, claim short-link scan, or NFC tap
+     * decides on a redirect destination - see the `scan_redirect` eventType.
+     */
+    redirectMode?: string;
     metadata?: Record<string, any>;
 }
 export interface AnalyticsTrackOptions {
@@ -171,6 +191,21 @@ export interface AnalyticsFilterRequest {
     claimIds?: string[];
     isAdmin?: boolean;
     hasLocation?: boolean;
+    /**
+     * Filter web-events rows by the `source` column (list-match). Web-events
+     * only - has no effect on `source: 'tag'` queries.
+     *
+     * There is deliberately no singular `source` filter: the request's own
+     * top-level `source` field (`'events'` vs `'tag'`) already owns that name
+     * as the table selector and predates this column - same word, two
+     * different things. Use a single-element array (`sources: ['portal']`)
+     * for an exact-match filter.
+     */
+    sources?: string[];
+    /** Filter tag-events rows by `redirectMode`. Tag-events only. */
+    redirectMode?: string;
+    /** Filter tag-events rows by `redirectMode` (list-match). Tag-events only. */
+    redirectModes?: string[];
 }
 export interface AnalyticsSummaryRequest extends AnalyticsFilterRequest {
     source: AnalyticsSource;
@@ -215,8 +250,8 @@ export interface AnalyticsTimeseriesResponse {
     metric: AnalyticsMetric;
     rows: AnalyticsTimeseriesRow[];
 }
-export type EventAnalyticsDimension = 'eventType' | 'country' | 'linkId' | 'href' | 'path' | 'appId' | 'destinationAppId' | 'deviceType' | 'isExternal' | 'productId' | 'proofId' | 'batchId' | 'variantId' | 'sessionId' | 'metadata';
-export type TagAnalyticsDimension = 'eventType' | 'country' | 'codeId' | 'claimId' | 'proofId' | 'productId' | 'batchId' | 'variantId' | 'deviceType' | 'sessionId' | 'isAdmin' | 'location' | 'metadata';
+export type EventAnalyticsDimension = 'eventType' | 'country' | 'linkId' | 'href' | 'path' | 'appId' | 'destinationAppId' | 'deviceType' | 'isExternal' | 'productId' | 'proofId' | 'batchId' | 'variantId' | 'sessionId' | 'metadata' | 'source';
+export type TagAnalyticsDimension = 'eventType' | 'country' | 'codeId' | 'claimId' | 'proofId' | 'productId' | 'batchId' | 'variantId' | 'deviceType' | 'sessionId' | 'isAdmin' | 'location' | 'metadata' | 'redirectMode';
 export interface AnalyticsBreakdownRequest extends AnalyticsFilterRequest {
     source: AnalyticsSource;
     dimension: EventAnalyticsDimension | TagAnalyticsDimension;

package/dist/types/authKit.d.ts

@@ -120,6 +120,96 @@ export interface AppleLoginOptions {
  * in `SmartlinksApiError.details`.
  */
 export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED';
+/**
+ * Details carried on the `MFA_REQUIRED` error thrown by {@link authKit.login} when the
+ * client's MFA policy requires a step-up. Surfaced as `err.details` (or
+ * `err.errorResponse.details`) on the `SmartlinksApiError` — `login()` never resolves in
+ * this case, it throws a 403 instead.
+ */
+export interface MfaRequiredDetails {
+    /** Short-lived (10 min) and single-use. Pass it to every challenge/finalize call below. */
+    mfaSessionToken: string;
+    /** Only factors the user actually enrolled. */
+    availableFactors: Array<'email' | 'sms'>;
+    /** `sms` is preferred over `email` when both are enrolled. */
+    preferredFactor: 'email' | 'sms';
+    maskedDestinations: {
+        email?: string;
+        sms?: string;
+    };
+}
+/** Response from {@link authKit.mfaChallengeSend}. */
+export interface MfaChallengeSendResponse {
+    success: true;
+    factor: 'email' | 'sms';
+    /** Masked, e.g. `"j***@x.com"` or `"+1******1234"`. */
+    destination: string;
+    /** ISO timestamp, 10 minutes from send. */
+    expiresAt: string;
+}
+/**
+ * Response from {@link authKit.mfaChallengeVerify} / {@link authKit.mfaRecoveryCode}.
+ * Same shape as a normal login response, plus trusted-device fields when the caller sent
+ * `trustDevice: true`.
+ */
+export interface MfaFinalizeResponse extends AuthLoginResponse {
+    /**
+     * Present only when the challenge was completed with `trustDevice: true`. Persist it
+     * alongside the refresh token (same secure storage) and send it as `trustedDeviceToken`
+     * on future {@link authKit.login} calls to skip the challenge on this device.
+     */
+    trustedDeviceToken?: string;
+    trustedDeviceExpiresAt?: string;
+}
+/** Response from {@link authKit.enrollEmailMfa} / {@link authKit.enrollSmsMfa}. */
+export interface MfaEnrollSendResponse {
+    mfaSessionToken: string;
+    destination: string;
+    expiresAt: string;
+}
+/** Response from {@link authKit.confirmEmailMfa} / {@link authKit.confirmSmsMfa}. */
+export interface MfaEnrolledResponse {
+    enrolled: true;
+    factor: 'email' | 'sms';
+}
+/** Response from {@link authKit.getMfaFactors}. */
+export interface MfaFactorsResponse {
+    enrolledFactors: {
+        email?: {
+            enrolledAt: string;
+            destination: string;
+        };
+        sms?: {
+            enrolledAt: string;
+            destination: string;
+        };
+    };
+    recoveryCodesRemaining: number;
+    mfaEnabledForClient: boolean;
+}
+/** One entry from {@link authKit.listTrustedDevices}. */
+export interface TrustedDevice {
+    id: string;
+    label: string | null;
+    createdAtMs: number;
+    lastUsedAtMs: number;
+    expiresAtMs: number;
+}
+/**
+ * Server-defined error codes for the step-up MFA flow, surfaced via
+ * `SmartlinksApiError.errorCode`.
+ *
+ * - `MFA_REQUIRED` (403) — from {@link authKit.login} only; see {@link MfaRequiredDetails}.
+ * - `INVALID_MFA_CODE` (401) — wrong code; let the user retry (attempts are capped, see next).
+ * - `MFA_TOO_MANY_ATTEMPTS` (429) — 5 wrong attempts; the challenge is burned, restart from `login()`.
+ * - `MFA_FACTOR_NOT_ENROLLED` (400) — requested factor isn't enrolled (or disabled for the
+ *   client) — a programming error if the UI only offers `availableFactors`.
+ * - `MFA_SESSION_EXPIRED` (401) — `mfaSessionToken` past its 10-minute TTL; restart from `login()`.
+ * - `MFA_SESSION_INVALID` (401) — unknown/wrong-client/already-consumed token, or (on enroll
+ *   confirm) mismatched user; restart the enroll/challenge flow.
+ * - `RECOVERY_CODE_INVALID` (401) — wrong or already-used recovery code.
+ */
+export type MfaErrorCode = 'MFA_REQUIRED' | 'INVALID_MFA_CODE' | 'MFA_TOO_MANY_ATTEMPTS' | 'MFA_FACTOR_NOT_ENROLLED' | 'MFA_SESSION_EXPIRED' | 'MFA_SESSION_INVALID' | 'RECOVERY_CODE_INVALID';
 export interface MagicLinkSendResponse {
     success: boolean;
     message: string;