@proveanything/smartlinks 1.1.11 → 1.1.13

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.1.11  |  Generated: 2025-12-26T15:12:34.830Z
+Version: 1.1.13  |  Generated: 2025-12-28T23:26:13.738Z
 
 This is a concise summary of all available API functions and types.
 
@@ -47,6 +47,8 @@ The Smartlinks SDK is organized into the following namespaces:
 
 — Other —
 - **attestation** - Functions for attestation operations
+- **journeysAnalytics** - Functions for journeysAnalytics operations
+- **location** - Functions for location operations
 - **template** - Functions for template operations
 
 ## HTTP Utilities
@@ -600,6 +602,7 @@ interface RecipientWithOutcome {
 interface CommsRecipientIdsQuery {
   broadcastId?: string
   journeyId?: string
+  journeyStepId?: string
   idField?: IdField
   from?: string
   to?: string
@@ -834,8 +837,8 @@ interface PublicInteractionsCountsByOutcomeRequest {
 **PublicInteractionsByUserRequest** (interface)
 ```typescript
 interface PublicInteractionsByUserRequest {
-  appId: string
-  interactionId: string
+  appId?: string
+  interactionId?: string
   from?: string
   to?: string
   limit?: number
@@ -877,7 +880,7 @@ interface ActorWithOutcome {
 ```typescript
 interface InteractionEventBase {
   collectionId: string,
-  ordId: string,
+  orgId?: string,
   userId?: string
   contactId?: string
   interactionId: string
@@ -1053,6 +1056,121 @@ interface UpdateJourneyBody {
 }
 ```
 
+### journeysAnalytics
+
+**JourneyStatsRequest** (interface)
+```typescript
+interface JourneyStatsRequest {
+  idField?: IdField // 'userId' | 'contactId'
+  from?: string
+  to?: string
+  finalStepId?: string
+  stepMappings?: Array<{ stepId: string; interactionId?: string; outcome?: string }>
+}
+```
+
+**JourneyStatsResponse** (interface)
+```typescript
+interface JourneyStatsResponse {
+  journeyId: string
+  totalEntered: number
+  currentlyActive?: number
+  completed?: number
+  exitedViaGoal?: number
+  lastUpdated: string
+  stepStats: Array<{ stepId: string; entered: number; completed: number; pending: number }>
+}
+```
+
+**JourneyStepRecipientsRequest** (interface)
+```typescript
+interface JourneyStepRecipientsRequest {
+  status?: 'entered' | 'completed' | 'pending'
+  idField?: IdField
+  interactionId?: string
+  outcome?: string
+  from?: string
+  to?: string
+  limit?: number
+}
+```
+
+**JourneyFunnelReportRequest** (interface)
+```typescript
+interface JourneyFunnelReportRequest {
+  idField?: IdField
+  periodStart?: string
+  periodEnd?: string
+  stepMappings: Array<{ stepId: string; interactionId?: string; outcome?: string }>
+}
+```
+
+**JourneyFunnelReportResponse** (interface)
+```typescript
+interface JourneyFunnelReportResponse {
+  journeyId: string
+  periodStart: string | null
+  periodEnd: string | null
+  steps: Array<{
+  stepId: string
+  enteredCount: number
+  completedCount: number
+  conversionRate: number
+  avgTimeToComplete: number | null
+  }>
+}
+```
+
+**JourneyStepRecipientsResponse** = `string[]`
+
+### location
+
+**Location** (interface)
+```typescript
+interface Location {
+  locationId: string
+  collectionId: string | null
+  scope: 'global' | 'collection'
+  name: string
+  category?: string
+  description?: string
+  countryName?: string
+  countryCode?: string
+  websiteUrl?: string
+  logoUrl?: string
+  phone?: string
+  email?: string
+  geofence?: Geofence | {}
+  metadata?: Record<string, unknown>
+  createdAt: string
+  updatedAt: string
+}
+```
+
+**LocationSearchQuery** (interface)
+```typescript
+interface LocationSearchQuery {
+  q?: string
+  category?: string
+  countryCode?: string
+  countryName?: string
+  limit?: number // default 20; max 100
+  sort?: 'name' | 'countryCode' | 'countryName' // default 'name'
+}
+```
+
+**LocationSearchResponse** (interface)
+```typescript
+interface LocationSearchResponse {
+  items: Location[]
+  count: number
+}
+```
+
+**Geofence** = ``
+
+**LocationPayload** = `Omit<`
+
 ### nfc
 
 **NfcTagInfo** (interface)
@@ -1953,6 +2071,43 @@ Appends one interaction event from a public source.
 **remove**(collectionId: string,
     id: string) → `Promise<void>`
 
+### journeysAnalytics
+
+**stats**(collectionId: string,
+    journeyId: string,
+    body: JourneyStatsRequest = {}) → `Promise<JourneyStatsResponse>`
+POST /admin/collection/:collectionId/journeys.analytics/:journeyId/stats Computes journey stats over a time window; outcome defaults to 'success'. If `finalStepId` is provided, includes `currentlyActive` and `completed` fields.
+
+**recipients**(collectionId: string,
+    journeyId: string,
+    stepId: string,
+    body: JourneyStepRecipientsRequest = {}) → `Promise<JourneyStepRecipientsResponse>`
+POST /admin/collection/:collectionId/journeys.analytics/:journeyId/steps/:stepId/recipients Returns recipient IDs for a given journey step. For completed/pending, `interactionId` is required; outcome defaults to 'success'.
+
+**funnelReport**(collectionId: string,
+    journeyId: string,
+    body: JourneyFunnelReportRequest) → `Promise<JourneyFunnelReportResponse>`
+POST /admin/collection/:collectionId/journeys.analytics/:journeyId/funnel-report Computes conversion, counts, and avg time across mapped steps in a period.
+
+### location
+
+**createGlobal**(params: LocationPayload) → `Promise<Location>`
+Platform: Create a global location (super admin; requires features.adminApps) POST /platform/location
+
+**create**(collectionId: string, params: LocationPayload) → `Promise<Location>`
+Admin: Create a collection-scoped location POST /admin/collection/:collectionId/location
+
+**search**(collectionId: string,
+    query: LocationSearchQuery = {}) → `Promise<LocationSearchResponse>`
+Admin: Search locations to pick during setup (combines collection + global) GET /admin/collection/:collectionId/location/search
+
+**getPublic**(locationId: string) → `Promise<Location>`
+Public: Fetch a global location by ID GET /public/location/:locationId
+
+**getPublicForCollection**(collectionId: string,
+    locationId: string) → `Promise<Location>`
+Public: Fetch a location for a collection; returns either a collection-owned or global fallback GET /public/collection/:collectionId/location/:locationId
+
 ### nfc
 
 **claimTag**(data: NfcClaimTagRequest) → `Promise<NfcTagInfo>`

package/dist/api/index.d.ts

@@ -19,7 +19,9 @@ export { contact } from "./contact";
 export { broadcasts } from "./broadcasts";
 export { segments } from "./segments";
 export { journeys } from "./journeys";
+export { journeysAnalytics } from "./journeysAnalytics";
 export { qr } from "./qr";
 export { template } from "./template";
 export { interactions } from "./interactions";
+export { location } from "./location";
 export type { AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto } from "./ai";

package/dist/api/index.js

@@ -21,6 +21,8 @@ export { contact } from "./contact";
 export { broadcasts } from "./broadcasts";
 export { segments } from "./segments";
 export { journeys } from "./journeys";
+export { journeysAnalytics } from "./journeysAnalytics";
 export { qr } from "./qr";
 export { template } from "./template";
 export { interactions } from "./interactions";
+export { location } from "./location";

package/dist/api/journeysAnalytics.d.ts

@@ -0,0 +1,20 @@
+import type { JourneyStatsRequest, JourneyStatsResponse, JourneyStepRecipientsRequest, JourneyStepRecipientsResponse, JourneyFunnelReportRequest, JourneyFunnelReportResponse } from "../types/journeysAnalytics";
+export declare namespace journeysAnalytics {
+    /**
+     * POST /admin/collection/:collectionId/journeys.analytics/:journeyId/stats
+     * Computes journey stats over a time window; outcome defaults to 'success'.
+     * If `finalStepId` is provided, includes `currentlyActive` and `completed` fields.
+     */
+    function stats(collectionId: string, journeyId: string, body?: JourneyStatsRequest): Promise<JourneyStatsResponse>;
+    /**
+     * POST /admin/collection/:collectionId/journeys.analytics/:journeyId/steps/:stepId/recipients
+     * Returns recipient IDs for a given journey step.
+     * For completed/pending, `interactionId` is required; outcome defaults to 'success'.
+     */
+    function recipients(collectionId: string, journeyId: string, stepId: string, body?: JourneyStepRecipientsRequest): Promise<JourneyStepRecipientsResponse>;
+    /**
+     * POST /admin/collection/:collectionId/journeys.analytics/:journeyId/funnel-report
+     * Computes conversion, counts, and avg time across mapped steps in a period.
+     */
+    function funnelReport(collectionId: string, journeyId: string, body: JourneyFunnelReportRequest): Promise<JourneyFunnelReportResponse>;
+}

package/dist/api/journeysAnalytics.js

@@ -0,0 +1,34 @@
+// src/api/journeysAnalytics.ts
+import { post } from "../http";
+export var journeysAnalytics;
+(function (journeysAnalytics) {
+    /**
+     * POST /admin/collection/:collectionId/journeys.analytics/:journeyId/stats
+     * Computes journey stats over a time window; outcome defaults to 'success'.
+     * If `finalStepId` is provided, includes `currentlyActive` and `completed` fields.
+     */
+    async function stats(collectionId, journeyId, body = {}) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/journeys.analytics/${encodeURIComponent(journeyId)}/stats`;
+        return post(path, body);
+    }
+    journeysAnalytics.stats = stats;
+    /**
+     * POST /admin/collection/:collectionId/journeys.analytics/:journeyId/steps/:stepId/recipients
+     * Returns recipient IDs for a given journey step.
+     * For completed/pending, `interactionId` is required; outcome defaults to 'success'.
+     */
+    async function recipients(collectionId, journeyId, stepId, body = {}) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/journeys.analytics/${encodeURIComponent(journeyId)}/steps/${encodeURIComponent(stepId)}/recipients`;
+        return post(path, body);
+    }
+    journeysAnalytics.recipients = recipients;
+    /**
+     * POST /admin/collection/:collectionId/journeys.analytics/:journeyId/funnel-report
+     * Computes conversion, counts, and avg time across mapped steps in a period.
+     */
+    async function funnelReport(collectionId, journeyId, body) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/journeys.analytics/${encodeURIComponent(journeyId)}/funnel-report`;
+        return post(path, body);
+    }
+    journeysAnalytics.funnelReport = funnelReport;
+})(journeysAnalytics || (journeysAnalytics = {}));

package/dist/api/location.d.ts

@@ -0,0 +1,28 @@
+import type { Location, LocationPayload, LocationSearchQuery, LocationSearchResponse } from "../types/location";
+export declare namespace location {
+    /**
+     * Platform: Create a global location (super admin; requires features.adminApps)
+     * POST /platform/location
+     */
+    function createGlobal(params: LocationPayload): Promise<Location>;
+    /**
+     * Admin: Create a collection-scoped location
+     * POST /admin/collection/:collectionId/location
+     */
+    function create(collectionId: string, params: LocationPayload): Promise<Location>;
+    /**
+     * Admin: Search locations to pick during setup (combines collection + global)
+     * GET /admin/collection/:collectionId/location/search
+     */
+    function search(collectionId: string, query?: LocationSearchQuery): Promise<LocationSearchResponse>;
+    /**
+     * Public: Fetch a global location by ID
+     * GET /public/location/:locationId
+     */
+    function getPublic(locationId: string): Promise<Location>;
+    /**
+     * Public: Fetch a location for a collection; returns either a collection-owned or global fallback
+     * GET /public/collection/:collectionId/location/:locationId
+     */
+    function getPublicForCollection(collectionId: string, locationId: string): Promise<Location>;
+}

package/dist/api/location.js

@@ -0,0 +1,69 @@
+// src/api/location.ts
+import { request, post } from "../http";
+function buildQueryString(q = {}) {
+    var _a, _b;
+    const params = new URLSearchParams();
+    if (q.q)
+        params.set('q', q.q);
+    if (q.category)
+        params.set('category', q.category);
+    if (q.countryCode)
+        params.set('countryCode', q.countryCode);
+    if (q.countryName)
+        params.set('countryName', q.countryName);
+    const limit = Math.min(Math.max((_a = q.limit) !== null && _a !== void 0 ? _a : 20, 1), 100);
+    params.set('limit', String(limit));
+    const sort = ((_b = q.sort) !== null && _b !== void 0 ? _b : 'name');
+    params.set('sort', sort);
+    const s = params.toString();
+    return s ? `?${s}` : '';
+}
+export var location;
+(function (location) {
+    /**
+     * Platform: Create a global location (super admin; requires features.adminApps)
+     * POST /platform/location
+     */
+    async function createGlobal(params) {
+        const path = `/platform/location`;
+        return post(path, params);
+    }
+    location.createGlobal = createGlobal;
+    /**
+     * Admin: Create a collection-scoped location
+     * POST /admin/collection/:collectionId/location
+     */
+    async function create(collectionId, params) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/location`;
+        return post(path, params);
+    }
+    location.create = create;
+    /**
+     * Admin: Search locations to pick during setup (combines collection + global)
+     * GET /admin/collection/:collectionId/location/search
+     */
+    async function search(collectionId, query = {}) {
+        const qs = buildQueryString(query);
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/location/search${qs}`;
+        return request(path);
+    }
+    location.search = search;
+    /**
+     * Public: Fetch a global location by ID
+     * GET /public/location/:locationId
+     */
+    async function getPublic(locationId) {
+        const path = `/public/location/${encodeURIComponent(locationId)}`;
+        return request(path);
+    }
+    location.getPublic = getPublic;
+    /**
+     * Public: Fetch a location for a collection; returns either a collection-owned or global fallback
+     * GET /public/collection/:collectionId/location/:locationId
+     */
+    async function getPublicForCollection(collectionId, locationId) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/location/${encodeURIComponent(locationId)}`;
+        return request(path);
+    }
+    location.getPublicForCollection = getPublicForCollection;
+})(location || (location = {}));

package/dist/types/comms.d.ts

@@ -133,6 +133,7 @@ export interface RecipientWithOutcome {
 export interface CommsRecipientIdsQuery {
     broadcastId?: string;
     journeyId?: string;
+    journeyStepId?: string;
     idField?: IdField;
     from?: string;
     to?: string;

package/dist/types/index.d.ts

@@ -15,6 +15,8 @@ export * from "./broadcasts";
 export * from "./segments";
 export * from "./common";
 export * from "./journeys";
+export * from "./journeysAnalytics";
 export * from "./qr";
 export * from "./template";
 export * from "./interaction";
+export * from "./location";

package/dist/types/index.js

@@ -17,6 +17,8 @@ export * from "./broadcasts";
 export * from "./segments";
 export * from "./common";
 export * from "./journeys";
+export * from "./journeysAnalytics";
 export * from "./qr";
 export * from "./template";
 export * from "./interaction";
+export * from "./location";

package/dist/types/interaction.d.ts

@@ -36,8 +36,8 @@ export interface PublicInteractionsCountsByOutcomeRequest {
     limit?: number;
 }
 export interface PublicInteractionsByUserRequest {
-    appId: string;
-    interactionId: string;
+    appId?: string;
+    interactionId?: string;
     from?: string;
     to?: string;
     limit?: number;
@@ -66,7 +66,7 @@ export interface ActorWithOutcome {
 }
 export interface InteractionEventBase {
     collectionId: string;
-    ordId: string;
+    orgId?: string;
     userId?: string;
     contactId?: string;
     interactionId: string;

package/dist/types/journeysAnalytics.d.ts

@@ -0,0 +1,58 @@
+import type { IdField } from './common';
+export interface JourneyStatsRequest {
+    idField?: IdField;
+    from?: string;
+    to?: string;
+    finalStepId?: string;
+    stepMappings?: Array<{
+        stepId: string;
+        interactionId?: string;
+        outcome?: string;
+    }>;
+}
+export interface JourneyStatsResponse {
+    journeyId: string;
+    totalEntered: number;
+    currentlyActive?: number;
+    completed?: number;
+    exitedViaGoal?: number;
+    lastUpdated: string;
+    stepStats: Array<{
+        stepId: string;
+        entered: number;
+        completed: number;
+        pending: number;
+    }>;
+}
+export interface JourneyStepRecipientsRequest {
+    status?: 'entered' | 'completed' | 'pending';
+    idField?: IdField;
+    interactionId?: string;
+    outcome?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+}
+export type JourneyStepRecipientsResponse = string[];
+export interface JourneyFunnelReportRequest {
+    idField?: IdField;
+    periodStart?: string;
+    periodEnd?: string;
+    stepMappings: Array<{
+        stepId: string;
+        interactionId?: string;
+        outcome?: string;
+    }>;
+}
+export interface JourneyFunnelReportResponse {
+    journeyId: string;
+    periodStart: string | null;
+    periodEnd: string | null;
+    steps: Array<{
+        stepId: string;
+        enteredCount: number;
+        completedCount: number;
+        conversionRate: number;
+        avgTimeToComplete: number | null;
+    }>;
+}

package/dist/types/journeysAnalytics.js

@@ -0,0 +1,2 @@
+// src/types/journeysAnalytics.ts
+export {};

package/dist/types/location.d.ts

@@ -0,0 +1,41 @@
+export type Geofence = {
+    type: 'bbox';
+    minLat: number;
+    minLon: number;
+    maxLat: number;
+    maxLon: number;
+} | {
+    type: 'polygon';
+    coordinates: Array<[lat: number, lon: number]>;
+} | Record<string, unknown>;
+export type LocationPayload = Omit<Location, 'locationId' | 'collectionId' | 'scope' | 'createdAt' | 'updatedAt'>;
+export interface Location {
+    locationId: string;
+    collectionId: string | null;
+    scope: 'global' | 'collection';
+    name: string;
+    category?: string;
+    description?: string;
+    countryName?: string;
+    countryCode?: string;
+    websiteUrl?: string;
+    logoUrl?: string;
+    phone?: string;
+    email?: string;
+    geofence?: Geofence | {};
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LocationSearchQuery {
+    q?: string;
+    category?: string;
+    countryCode?: string;
+    countryName?: string;
+    limit?: number;
+    sort?: 'name' | 'countryCode' | 'countryName';
+}
+export interface LocationSearchResponse {
+    items: Location[];
+    count: number;
+}

package/dist/types/location.js

@@ -0,0 +1,2 @@
+// src/types/location.ts
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",