@proveanything/smartlinks 1.1.10 → 1.1.12

package/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.1.10  |  Generated: 2025-12-24T21:01:46.345Z
+Version: 1.1.12  |  Generated: 2025-12-28T18:01:35.628Z
 
 This is a concise summary of all available API functions and types.
 
@@ -29,6 +29,9 @@ The Smartlinks SDK is organized into the following namespaces:
 - **broadcasts** - Define broadcast campaigns; append recipients/events; analytics and CRUD.
 - **segments** - Define dynamic/static audience segments; estimate and list recipients; schedule calculations.
 
+— Analytics & Events —
+- **interactions** - Log and analyze interactions/outcomes; aggregates and actor lists; interaction definition CRUD.
+
 — Automation —
 - **journeys** - Configure automated flows triggered by events or schedules; steps, rules; full CRUD.
 
@@ -44,7 +47,7 @@ The Smartlinks SDK is organized into the following namespaces:
 
 — Other —
 - **attestation** - Functions for attestation operations
-- **interactions** - Functions for interactions operations
+- **location** - Functions for location operations
 - **template** - Functions for template operations
 
 ## HTTP Utilities
@@ -832,8 +835,8 @@ interface PublicInteractionsCountsByOutcomeRequest {
 **PublicInteractionsByUserRequest** (interface)
 ```typescript
 interface PublicInteractionsByUserRequest {
-  appId: string
-  interactionId: string
+  appId?: string
+  interactionId?: string
   from?: string
   to?: string
   limit?: number
@@ -875,7 +878,7 @@ interface ActorWithOutcome {
 ```typescript
 interface InteractionEventBase {
   collectionId: string,
-  ordId: string,
+  orgId?: string,
   userId?: string
   contactId?: string
   interactionId: string
@@ -1051,6 +1054,54 @@ interface UpdateJourneyBody {
 }
 ```
 
+### 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)
@@ -1880,23 +1931,23 @@ Delete a form for a collection (admin only).
 
 **byUser**(collectionId: string,
     query: AdminInteractionsByUserRequest = {}) → `Promise<InteractionEventRow[]>`
-POST /admin/collection/:collectionId/interaction/by-user Returns BigQuery interaction rows, newest first.
+POST /admin/collection/:collectionId/interactions/by-user Returns BigQuery interaction rows, newest first.
 
 **countsByOutcome**(collectionId: string,
     query: AdminInteractionsCountsByOutcomeRequest = {}) → `Promise<OutcomeCount[]>`
-POST /admin/collection/:collectionId/interaction/counts-by-outcome Returns array of { outcome, count }.
+POST /admin/collection/:collectionId/interactions/counts-by-outcome Returns array of { outcome, count }.
 
 **actorIdsByInteraction**(collectionId: string,
     query: AdminActorIdsByInteractionRequest) → `Promise<ActorId[] | ActorWithOutcome[]>`
-POST /admin/collection/:collectionId/interaction/actor-ids/by-interaction Returns list of IDs, optionally with outcome when includeOutcome=true.
+POST /admin/collection/:collectionId/interactions/actor-ids/by-interaction Returns list of IDs, optionally with outcome when includeOutcome=true.
 
 **appendEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<`
-POST /admin/collection/:collectionId/interaction/append Appends one interaction event.
+POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
 
 **updateEvent**(collectionId: string,
     body: UpdateInteractionBody) → `Promise<`
-POST /admin/collection/:collectionId/interaction/append Appends one interaction event.
+POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
 
 **submitPublicEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<`
@@ -1951,6 +2002,25 @@ Appends one interaction event from a public source.
 **remove**(collectionId: string,
     id: string) → `Promise<void>`
 
+### 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

@@ -22,4 +22,5 @@ export { journeys } from "./journeys";
 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

@@ -24,3 +24,4 @@ export { journeys } from "./journeys";
 export { qr } from "./qr";
 export { template } from "./template";
 export { interactions } from "./interactions";
+export { location } from "./location";

package/dist/api/interactions.d.ts

@@ -1,22 +1,22 @@
 import type { AdminInteractionsByUserRequest, AdminInteractionsCountsByOutcomeRequest, AdminActorIdsByInteractionRequest, AppendInteractionBody, UpdateInteractionBody, OutcomeCount, ActorId, ActorWithOutcome, InteractionEventRow, PublicInteractionsCountsByOutcomeRequest, PublicInteractionsByUserRequest, CreateInteractionTypeBody, UpdateInteractionTypeBody, ListInteractionTypesQuery, InteractionTypeRecord, InteractionTypeList } from "../types/interaction";
 export declare namespace interactions {
     /**
-     * POST /admin/collection/:collectionId/interaction/by-user
+     * POST /admin/collection/:collectionId/interactions/by-user
      * Returns BigQuery interaction rows, newest first.
      */
     function byUser(collectionId: string, query?: AdminInteractionsByUserRequest): Promise<InteractionEventRow[]>;
     /**
-     * POST /admin/collection/:collectionId/interaction/counts-by-outcome
+     * POST /admin/collection/:collectionId/interactions/counts-by-outcome
      * Returns array of { outcome, count }.
      */
     function countsByOutcome(collectionId: string, query?: AdminInteractionsCountsByOutcomeRequest): Promise<OutcomeCount[]>;
     /**
-     * POST /admin/collection/:collectionId/interaction/actor-ids/by-interaction
+     * POST /admin/collection/:collectionId/interactions/actor-ids/by-interaction
      * Returns list of IDs, optionally with outcome when includeOutcome=true.
      */
     function actorIdsByInteraction(collectionId: string, query: AdminActorIdsByInteractionRequest): Promise<ActorId[] | ActorWithOutcome[]>;
     /**
-     * POST /admin/collection/:collectionId/interaction/append
+     * POST /admin/collection/:collectionId/interactions/append
      * Appends one interaction event.
      */
     function appendEvent(collectionId: string, body: AppendInteractionBody): Promise<{

package/dist/api/interactions.js

@@ -18,41 +18,41 @@ function encodeQuery(params) {
 export var interactions;
 (function (interactions) {
     /**
-     * POST /admin/collection/:collectionId/interaction/by-user
+     * POST /admin/collection/:collectionId/interactions/by-user
      * Returns BigQuery interaction rows, newest first.
      */
     async function byUser(collectionId, query = {}) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/by-user`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/by-user`;
         return post(path, query);
     }
     interactions.byUser = byUser;
     /**
-     * POST /admin/collection/:collectionId/interaction/counts-by-outcome
+     * POST /admin/collection/:collectionId/interactions/counts-by-outcome
      * Returns array of { outcome, count }.
      */
     async function countsByOutcome(collectionId, query = {}) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/counts-by-outcome`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/counts-by-outcome`;
         return post(path, query);
     }
     interactions.countsByOutcome = countsByOutcome;
     /**
-     * POST /admin/collection/:collectionId/interaction/actor-ids/by-interaction
+     * POST /admin/collection/:collectionId/interactions/actor-ids/by-interaction
      * Returns list of IDs, optionally with outcome when includeOutcome=true.
      */
     async function actorIdsByInteraction(collectionId, query) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/actor-ids/by-interaction`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/actor-ids/by-interaction`;
         return post(path, query);
     }
     interactions.actorIdsByInteraction = actorIdsByInteraction;
     /**
-     * POST /admin/collection/:collectionId/interaction/append
+     * POST /admin/collection/:collectionId/interactions/append
      * Appends one interaction event.
      */
     async function appendEvent(collectionId, body) {
         if (!body.userId && !body.contactId) {
             throw new Error("AppendInteractionBody must include one of userId or contactId");
         }
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/append`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/append`;
         return post(path, body);
     }
     interactions.appendEvent = appendEvent;
@@ -60,7 +60,7 @@ export var interactions;
         if (!body.userId && !body.contactId) {
             throw new Error("AppendInteractionBody must include one of userId or contactId");
         }
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/append`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/append`;
         return post(path, body);
     }
     interactions.updateEvent = updateEvent;
@@ -71,46 +71,46 @@ export var interactions;
         if (!body.userId && !body.contactId) {
             throw new Error("AppendInteractionBody must include one of userId or contactId");
         }
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/interaction/submit`;
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/interactions/submit`;
         return post(path, body);
     }
     interactions.submitPublicEvent = submitPublicEvent;
     // CRUD: Interaction Types (Postgres)
     async function create(collectionId, body) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/`;
         return post(path, body);
     }
     interactions.create = create;
     async function list(collectionId, query = {}) {
         const qs = encodeQuery(query);
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/${qs}`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/${qs}`;
         return request(path);
     }
     interactions.list = list;
     async function get(collectionId, id) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/${encodeURIComponent(id)}`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/${encodeURIComponent(id)}`;
         return request(path);
     }
     interactions.get = get;
     async function update(collectionId, id, patchBody) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/${encodeURIComponent(id)}`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/${encodeURIComponent(id)}`;
         return patch(path, patchBody);
     }
     interactions.update = update;
     async function remove(collectionId, id) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interaction/${encodeURIComponent(id)}`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/${encodeURIComponent(id)}`;
         return del(path);
     }
     interactions.remove = remove;
     // Public endpoints (permission-aware)
     async function publicCountsByOutcome(collectionId, body, authToken) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/interaction/counts-by-outcome`;
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/interactions/counts-by-outcome`;
         const headers = authToken ? { AUTHORIZATION: `Bearer ${authToken}` } : undefined;
         return post(path, body, headers);
     }
     interactions.publicCountsByOutcome = publicCountsByOutcome;
     async function publicMyInteractions(collectionId, body, authToken) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/interaction/by-user`;
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/interactions/by-user`;
         const headers = authToken ? { AUTHORIZATION: `Bearer ${authToken}` } : undefined;
         return post(path, body, headers);
     }

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/index.d.ts

@@ -18,3 +18,4 @@ export * from "./journeys";
 export * from "./qr";
 export * from "./template";
 export * from "./interaction";
+export * from "./location";

package/dist/types/index.js

@@ -20,3 +20,4 @@ export * from "./journeys";
 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/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.10",
+  "version": "1.1.12",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",