@proveanything/smartlinks 2.0.39 → 2.0.41

package/dist/api/interactions.d.ts

@@ -1,4 +1,4 @@
-import type { AdminInteractionsCountsByOutcomeRequest, AdminInteractionsQueryRequest, AdminInteractionsAggregateRequest, AdminInteractionsAggregateResponse, AppendInteractionBody, UpdateInteractionBody, OutcomeCount, InteractionEventRow, PublicInteractionsCountsByOutcomeRequest, PublicInteractionsByUserRequest, SubmitInteractionResponse, SubmitInteractionError, CreateInteractionTypeBody, UpdateInteractionTypeBody, ListInteractionTypesQuery, InteractionTypeRecord, InteractionTypeList } from "../types/interaction.js";
+import type { AdminInteractionsCountsByOutcomeRequest, AdminInteractionsQueryRequest, AdminInteractionsAggregateRequest, AdminInteractionsAggregateResponse, AppendInteractionBody, UpdateInteractionBody, OutcomeCount, InteractionEventRow, PublicInteractionsCountsByOutcomeRequest, PublicInteractionsByUserRequest, SubmitInteractionResponse, SubmitInteractionError, CreateInteractionTypeBody, EnsureInteractionTypeInput, UpdateInteractionTypeBody, ListInteractionTypesQuery, InteractionTypeRecord, InteractionTypeList } from "../types/interaction.js";
 export declare namespace interactions {
     /**
      * POST /admin/collection/:collectionId/interactions/query
@@ -45,6 +45,19 @@ export declare namespace interactions {
     function submitPublicEvent(collectionId: string, body: AppendInteractionBody): Promise<SubmitInteractionResponse | SubmitInteractionError>;
     function create(collectionId: string, body: CreateInteractionTypeBody): Promise<InteractionTypeRecord>;
     function list(collectionId: string, query?: ListInteractionTypesQuery): Promise<InteractionTypeList>;
+    /**
+     * Find this app's interaction type by its readable `key` (data.interactionType), or create it.
+     * Returns the type record — its `id` is the server-minted UUID every event must use.
+     * ADMIN only (run it in your admin/setup screen), then store the id in your app config so
+     * public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup.
+     *
+     * @example
+     * const vote = await SL.interactions.ensureType(collectionId, {
+     *   appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true },
+     * })
+     * // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
+     */
+    function ensureType(collectionId: string, input: EnsureInteractionTypeInput): Promise<InteractionTypeRecord>;
     function get(collectionId: string, id: string): Promise<InteractionTypeRecord>;
     function update(collectionId: string, id: string, patchBody: UpdateInteractionTypeBody): Promise<InteractionTypeRecord>;
     function remove(collectionId: string, id: string): Promise<void>;

package/dist/api/interactions.js

@@ -102,6 +102,33 @@ export var interactions;
         return request(path);
     }
     interactions.list = list;
+    /**
+     * Find this app's interaction type by its readable `key` (data.interactionType), or create it.
+     * Returns the type record — its `id` is the server-minted UUID every event must use.
+     * ADMIN only (run it in your admin/setup screen), then store the id in your app config so
+     * public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup.
+     *
+     * @example
+     * const vote = await SL.interactions.ensureType(collectionId, {
+     *   appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true },
+     * })
+     * // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
+     */
+    async function ensureType(collectionId, input) {
+        const { appId, key, permissions, display, data } = input;
+        if (!appId || !key)
+            throw new Error('interactions.ensureType: appId and key are required');
+        for (let offset = 0;; offset += 200) {
+            const page = await list(collectionId, { appId, limit: 200, offset });
+            const found = (page.items || []).find((t) => t.data && t.data.interactionType === key);
+            if (found)
+                return found;
+            if (!page.items || page.items.length < 200)
+                break;
+        }
+        return create(collectionId, Object.assign(Object.assign({ appId }, (permissions ? { permissions } : {})), { data: Object.assign(Object.assign(Object.assign({}, (data || {})), { interactionType: key }), (display ? { display } : {})) }));
+    }
+    interactions.ensureType = ensureType;
     async function get(collectionId, id) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/interactions/${encodeURIComponent(id)}`;
         return request(path);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.39  |  Generated: 2026-10-05T14:14:46.558Z
+Version: 2.0.41  |  Generated: 2026-10-06T07:00:42.791Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2539,6 +2539,7 @@ interface AppFunctionDef {
   elevated?: boolean;
   capabilities?: string[];
   dataScope?: 'collection' | 'global';
+  inputs?: AppFunctionInputs;
   apiVersion?: string;
   handler?: string;
   agent?: AppFunctionAgentExposure;
@@ -2622,6 +2623,27 @@ interface ServerFunctionContext {
   caller: ServerFunctionCaller;
   fetch: typeof fetch;
   log: (message: string, data?: Record<string, any>) => void;
+  inputs: Readonly<ServerFunctionInputs>;
+}
+```
+
+**AppFunctionInputs** (interface)
+```typescript
+interface AppFunctionInputs {
+  entity?: boolean;
+  collection?: boolean;
+  appConfig?: boolean;
+  product?: { from: `body.${string}` | `query.${string}` | 'path' };
+}
+```
+
+**ServerFunctionInputs** (interface)
+```typescript
+interface ServerFunctionInputs {
+  entity?: Record<string, any> | null;
+  collection?: Record<string, any> | null;
+  appConfig?: Record<string, any> | null;
+  product?: Record<string, any> | null;
 }
 ```
 
@@ -7275,13 +7297,24 @@ interface InteractionTypeList {
 **CreateInteractionTypeBody** (interface)
 ```typescript
 interface CreateInteractionTypeBody {
-  id: string
+  id?: string
   appId: string
   permissions?: InteractionPermissions
   data?: Record<string, unknown>
 }
 ```
 
+**EnsureInteractionTypeInput** (interface)
+```typescript
+interface EnsureInteractionTypeInput {
+  appId: string
+  key: string
+  permissions?: InteractionPermissions
+  display?: InteractionDisplay
+  data?: Record<string, unknown>
+}
+```
+
 **UpdateInteractionTypeBody** (interface)
 ```typescript
 interface UpdateInteractionTypeBody {
@@ -11325,36 +11358,40 @@ POST /api/v1/public/collection/:collectionId/interactions/submit Submits an inte
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
 POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
+**ensureType**(collectionId: string,
+    input: EnsureInteractionTypeInput) → `Promise<InteractionTypeRecord>`
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
+
 **get**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
 
 **update**(collectionId: string,
     id: string,
     patchBody: UpdateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
 
 **remove**(collectionId: string,
     id: string) → `Promise<void>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
 
 **publicCountsByOutcome**(collectionId: string,
     body: PublicInteractionsCountsByOutcomeRequest,
     authToken?: string) → `Promise<OutcomeCount[]>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
 
 **publicMyInteractions**(collectionId: string,
     body: PublicInteractionsByUserRequest,
     authToken?: string) → `Promise<InteractionEventRow[]>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
 
 **publicList**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
 
 **publicGet**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+Find this app's interaction type by its readable `key` (data.interactionType), or create it. Returns the type record — its `id` is the server-minted UUID every event must use. ADMIN only (run it in your admin/setup screen), then store the id in your app config so public code can read it: `interactionIds: { vote: type.id }`. Safe to run on every setup. const vote = await SL.interactions.ensureType(collectionId, { appId: 'my-app', key: 'vote', permissions: { allowPublicSubmit: true, uniquePerUser: true }, }) // vote.id → '52bab6fa-…' — store it in config; never hardcode 'vote' as an interactionId
 
 ### jobs