@proveanything/smartlinks 2.0.47 → 2.0.49

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.47  |  Generated: 2026-10-08T12:38:10.855Z
+Version: 2.0.49  |  Generated: 2026-10-09T10:14:16.325Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2401,6 +2401,17 @@ interface AppWidgetComponent {
   optional?: string[];
   };
   settings?: Record<string, any>;
+  styleSupport?: WidgetStyleSupport;
+}
+```
+
+**WidgetStyleSupport** (interface)
+```typescript
+interface WidgetStyleSupport {
+  accent?: boolean;
+  text?: boolean;
+  textAlign?: boolean;
+  background?: 'transparent' | 'own';
 }
 ```
 
@@ -5140,7 +5151,7 @@ interface PushSubscribeResponse {
 **RegisterPushMethodRequest** (interface)
 ```typescript
 interface RegisterPushMethodRequest {
-  contactId: string
+  contactId?: string
   endpoint: string
   keys: { p256dh: string; auth: string }
   meta?: Record<string, any>
@@ -5200,7 +5211,7 @@ interface CommsPublicTopicsResponse {
 **UnsubscribeQuery** (interface)
 ```typescript
 interface UnsubscribeQuery {
-  contactId: string
+  contactId?: string
   topic?: string
   channel?: BroadcastChannel
   token?: string
@@ -5214,10 +5225,26 @@ interface UnsubscribeResponse {
 }
 ```
 
+**CommsSignupRequest** (interface)
+```typescript
+interface CommsSignupRequest {
+  email: string
+  topics?: string[]
+  firstName?: string
+}
+```
+
+**CommsSignupResponse** (interface)
+```typescript
+interface CommsSignupResponse {
+  ok: true; pending: true
+}
+```
+
 **CommsConsentUpsertRequest** (interface)
 ```typescript
 interface CommsConsentUpsertRequest {
-  contactId: string
+  contactId?: string
   channels?: ConsentChannels
   topics?: Record<string, boolean>
   topicsByChannel?: Partial<Record<BroadcastChannel, Record<string, boolean>>>
@@ -5227,7 +5254,7 @@ interface CommsConsentUpsertRequest {
 **CommsPreferencesUpsertRequest** (interface)
 ```typescript
 interface CommsPreferencesUpsertRequest {
-  contactId: string
+  contactId?: string
   subject?: { type: SubjectType; id: string; productId?: string }
   channels?: ConsentChannels
   topics?: Record<string, boolean>
@@ -5238,7 +5265,7 @@ interface CommsPreferencesUpsertRequest {
 **CommsSubscribeRequest** (interface)
 ```typescript
 interface CommsSubscribeRequest {
-  contactId: string
+  contactId?: string
   subject: { type: SubjectType; id: string; productId?: string }
   subscribe: boolean
   source?: string
@@ -5255,7 +5282,7 @@ interface CommsSubscribeResponse {
 **CommsSubscriptionCheckQuery** (interface)
 ```typescript
 interface CommsSubscriptionCheckQuery {
-  contactId: string
+  contactId?: string
   subjectType: SubjectType
   subjectId: string
   productId?: string
@@ -5272,7 +5299,7 @@ interface CommsSubscriptionCheckResponse {
 **CommsListMethodsQuery** (interface)
 ```typescript
 interface CommsListMethodsQuery {
-  contactId: string
+  contactId?: string
   type?: BroadcastChannel
 }
 ```
@@ -5502,7 +5529,8 @@ export interface PushSubscribeResponse { ok: true; id: string }
 
 // Public: register a push contact method
 export interface RegisterPushMethodRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   endpoint: string
   keys: { p256dh: string; auth: string }
   meta?: Record<string, any>
@@ -5557,7 +5585,8 @@ export type CommsSettingsPatchBody = Partial<CommsSettings>
 export interface CommsPublicTopicsResponse { ok: true; topics: Record<string, TopicConfig> }
 
 export interface UnsubscribeQuery {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   topic?: string
   channel?: BroadcastChannel
   token?: string
@@ -5565,19 +5594,30 @@ export interface UnsubscribeQuery {
 
 export interface UnsubscribeResponse { ok: true; applied?: { channels?: Record<string, boolean>; topics?: Record<string, boolean> } }
 
+// Public sign-up (double opt-in)
+export interface CommsSignupRequest {
+  email: string
+  /** Topic ids from the collection's comm settings (e.g. ["newsletter"]). */
+  topics?: string[]
+  firstName?: string
+}
+export interface CommsSignupResponse { ok: true; pending: true }
+
 // Public consent/preferences/subscribe
 export type ConsentChannels = Partial<Record<BroadcastChannel, boolean>>
 type SubjectType = import('./contact').SubjectType
 
 export interface CommsConsentUpsertRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   channels?: ConsentChannels
   topics?: Record<string, boolean>
   topicsByChannel?: Partial<Record<BroadcastChannel, Record<string, boolean>>>
 }
 
 export interface CommsPreferencesUpsertRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   subject?: { type: SubjectType; id: string; productId?: string }
   channels?: ConsentChannels
   topics?: Record<string, boolean>
@@ -5585,7 +5625,8 @@ export interface CommsPreferencesUpsertRequest {
 }
 
 export interface CommsSubscribeRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   subject: { type: SubjectType; id: string; productId?: string }
   subscribe: boolean
   source?: string
@@ -5593,7 +5634,8 @@ export interface CommsSubscribeRequest {
 export interface CommsSubscribeResponse { ok: true; subscriptionId: string }
 
 export interface CommsSubscriptionCheckQuery {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   subjectType: SubjectType
   subjectId: string
   productId?: string
@@ -5601,7 +5643,8 @@ export interface CommsSubscriptionCheckQuery {
 export interface CommsSubscriptionCheckResponse { ok: true; subscribed: boolean }
 
 export interface CommsListMethodsQuery {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   type?: BroadcastChannel
 }
 export interface CommsListMethodsResponse { ok: true; methods: import('./contact').CommMethod[] }
@@ -10921,82 +10964,86 @@ Invite a user to a collection by email (admin only). Creates or links their acco
 **getPushVapidPublicKey**(collectionId: string) → `Promise<import("../types/comms").PushVapidResponse>`
 Public: Get VAPID public key used for Web Push subscriptions. GET /public/collection/:collectionId/comm/push/vapidPublicKey Note: Key may be global; path is collection-scoped for consistency.
 
-**registerPush**(collectionId: string,
+**registerPush**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register a Web Push subscription under unified comms. POST /public/collection/:collectionId/comm/push/register
 
-**getSettings**(collectionId: string,
+**getSettings**(collectionId: string,
     opts: { includeSecret?: boolean } = {}) → `Promise<import("../types/comms").CommsSettingsGetResponse>`
 Admin: Get current comms settings for a collection. GET /admin/collection/:collectionId/comm.settings Optional query: includeSecret=true to include unsub.secret in response.
 
-**patchSettings**(collectionId: string,
+**patchSettings**(collectionId: string,
     body: import("../types/comms") → `void`
 Admin: Patch comms settings for a collection. PATCH /admin/collection/:collectionId/comm.settings
 
 **getPublicTopics**(collectionId: string) → `Promise<import("../types/comms").CommsPublicTopicsResponse>`
 Public: Fetch configured topics for a collection. GET /public/collection/:collectionId/comm/topics
 
-**unsubscribe**(collectionId: string,
+**unsubscribe**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: Unsubscribe a contact from a category or channel. GET /public/collection/:collectionId/comm/unsubscribe
 
-**upsertConsent**(collectionId: string,
+**signup**(collectionId: string,
+    body: import("../types/comms") → `void`
+Public: sign an email address up for topics (a newsletter, updates) — works signed out. Double opt-in: nothing is consented until the address's owner clicks the confirmation link SmartLinks emails them. Always answers `{ ok: true, pending: true }` (it never reveals whether the address is already known). Topics must be ones configured in the collection's comm settings. Set comm settings `signup.confirmedUrl` to send people to your own page after confirming. POST /public/collection/:collectionId/comm/signup
+
+**upsertConsent**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Upsert default consent for a contact. POST /public/collection/:collectionId/comm/consent
 
-**upsertPreferences**(collectionId: string,
+**upsertPreferences**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Upsert preferences for a specific subject (or default if subject omitted). POST /public/collection/:collectionId/comm/preferences
 
-**subscribe**(collectionId: string,
+**subscribe**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Subscribe/unsubscribe contact to a subject. POST /public/collection/:collectionId/comm/subscribe
 
-**checkSubscription**(collectionId: string,
+**checkSubscription**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: Check subscription status for a subject. GET /public/collection/:collectionId/comm/subscription/check
 
-**listMethods**(collectionId: string,
+**listMethods**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: List registered contact methods. GET /public/collection/:collectionId/comm/methods
 
-**registerEmail**(collectionId: string,
+**registerEmail**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register email method for a contact. POST /public/collection/:collectionId/comm/email/register
 
-**registerSms**(collectionId: string,
+**registerSms**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register SMS method for a contact. POST /public/collection/:collectionId/comm/sms/register
 
-**resolveSubscriptions**(collectionId: string,
+**resolveSubscriptions**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Resolve contacts for a subject with identity hints. POST /public/collection/:collectionId/comm/subscriptions/resolve
 
-**queryByUser**(collectionId: string,
+**queryByUser**(collectionId: string,
     body: CommsQueryByUser = {}) → `Promise<CommunicationEvent[]>`
 Analytics: Query communication events by user or contact. POST /admin/collection/:collectionId/comm/query/by-user
 
-**queryRecipientIds**(collectionId: string,
+**queryRecipientIds**(collectionId: string,
     body: CommsRecipientIdsQuery) → `Promise<RecipientId[]>`
 Analytics: Recipient IDs for a communication source. POST /admin/collection/:collectionId/comm/query/recipient-ids
 
-**queryRecipientsWithoutAction**(collectionId: string,
+**queryRecipientsWithoutAction**(collectionId: string,
     body: CommsRecipientsWithoutActionQuery) → `Promise<RecipientId[]>`
 Analytics: Recipients who did not perform an action. POST /admin/collection/:collectionId/comm/query/recipients/without-action
 
-**queryRecipientsWithAction**(collectionId: string,
+**queryRecipientsWithAction**(collectionId: string,
     body: CommsRecipientsWithActionQuery) → `Promise<RecipientId[] | RecipientWithOutcome[]>`
 Analytics: Recipients who performed an action, optionally with outcome. POST /admin/collection/:collectionId/comm/query/recipients/with-action
 
-**sendTransactional**(collectionId: string,
+**sendTransactional**(collectionId: string,
     body: TransactionalSendRequest) → `Promise<TransactionalSendResult>`
 Send a single transactional message to one contact using a template. No broadcast record is created. The send is logged to the contact's communication history with sourceType: 'transactional'. POST /admin/collection/:collectionId/comm/send ```typescript const result = await comms.sendTransactional(collectionId, { contactId:  'e4f2a1b0-...', templateId: 'warranty-update', channel:    'preferred', props:      { claimRef: 'CLM-0042', decision: 'approved' }, include:    { productId: 'prod-abc123', appCase: 'c9d1e2f3-...' }, ref:        'warranty-decision-notification', appId:      'warrantyApp', }) if (result.ok) { console.log(`Sent via ${result.channel}`, result.messageId) } else { console.error('Send failed:', result.error) } ```
 
-**logCommunicationEvent**(collectionId: string,
+**logCommunicationEvent**(collectionId: string,
     body: LogCommunicationEventBody) → `Promise<AppendResult>`
 Logging: Append a single communication event. POST /admin/collection/:collectionId/comm/log
 
-**logBulkCommunicationEvents**(collectionId: string,
+**logBulkCommunicationEvents**(collectionId: string,
     body: LogBulkCommunicationEventsBody | ({ sourceId: string; ids: string[]; idField?: 'userId'|'contactId'; [k: string]: any }) → `void`
 Logging: Append many communication events for a list of IDs. POST /admin/collection/:collectionId/comm/log/bulk
 

package/docs/comms.md

@@ -313,9 +313,30 @@ function effectivePolicy(topic: any, channel: 'email' | 'sms' | 'push' | 'wallet
 }
 ```
 
+### Sign-up with double opt-in (newsletters)
+
+For a sign-up form — works signed out. SmartLinks emails the address a "confirm your subscription"
+link; nothing is consented until it's clicked. The answer is always the same, so the form can't be
+used to find out who's registered.
+
+```typescript
+await comms.signup('collectionId', { email: 'sam@example.com', topics: ['newsletter'] })
+// → { ok: true, pending: true }  — tell the visitor to check their inbox
+```
+
+- Topics must exist in the collection's comm settings. Give a newsletter topic
+  `defaults.policy: 'opt-in'`: broadcasts on an opt-in topic only reach people who said yes
+  (confirmed sign-ups), never the whole contact list.
+- Confirming turns on the email channel and the topics, and marks the address verified.
+- Set comm settings `signup.confirmedUrl` (https) to send people to your own "thanks" page after
+  they confirm (`?confirmed=1`, or `0` for an expired link); otherwise SmartLinks shows a short page.
+
 ### Consent (Default)
 
-Record a contact's default channel and topic opt-ins.
+Record a contact's default channel and topic opt-ins. These calls (consent, preferences, subscribe,
+methods, push/email/SMS registration) act for the **signed-in** contact — `contactId` may be omitted
+to mean "me"; only collection admins may name another contact. An email registered here is verified
+only if it's the one the user signed in with; any other address is sent a confirmation link.
 
 ```typescript
 await comms.upsertConsent('collectionId', {

package/docs/deploying-apps.md

@@ -165,6 +165,17 @@ The canonical channels are **`dev` · `alpha` · `beta` · `stable`**. Legacy `p
 A collection chooses which channel it follows, so you can point a test collection at `dev`
 and exercise a build before it reaches `prod`.
 
+### `preview` — server code while you build (Forge)
+
+Forge publishes an app's **server functions only** to a private `preview` channel whenever the
+agent changes them, so the app's own preview can call the new code straight away. It is not a
+channel a collection can follow, release to or promote from. A preview call runs only with the
+**preview pass** Forge gives its preview — for one app on one collection, for a few hours — so
+nobody else ever runs in-progress server code, while the builder can preview against any
+collection they administer. The SDK sends the pass automatically (`SL.functions` with
+`appChannel: 'preview'` and `slPreview` in the context); apps need no code for it. `dev` only
+changes when you choose to release to it.
+
 ---
 
 ## Deploy keys

package/docs/widgets.md

@@ -651,6 +651,78 @@ Widgets use semantic class names that reference these variables:
 <Button className="bg-blue-500 text-white">
 ```
 
+### Style support — how a widget takes styling from where it's placed
+
+Hosts that place widgets (Link Page, Hub, …) offer per-widget styling: width, alignment, padding,
+scale, corners, border, background, and colours. The host only ever styles the **box** around the
+widget; it never reaches inside (no selector tricks, no `!important`). So a widget **declares** what
+it honours, the host shows only those controls, and colours reach the widget through variables.
+
+**Declare it** on the widget's entry in `app.manifest.json` (`widgets.components[]`):
+
+```jsonc
+{
+  "name": "TapToDonate",
+  "styleSupport": {
+    "accent": true,          // reads --sl-widget-accent / --sl-widget-accent-contrast
+    "text": true,            // reads --sl-widget-text
+    "textAlign": true,       // titles/messages use text-align: inherit
+    "background": "transparent"  // or "own" if it paints its own card
+  }
+}
+```
+
+List only what you actually implemented. No `styleSupport` (older widgets) → the host offers layout
+controls only and says the widget has no colour customisation; nothing breaks.
+
+| Setting | Owner | Works when |
+|---|---|---|
+| width, alignment, padding, scale | Host | always (scale: keep 60–130%) |
+| radius, border | Host | always — visible when the widget is transparent or fills its box |
+| background | Host | the widget is transparent (hidden when `background: "own"`) |
+| text | Widget | declared, and the widget reads `--sl-widget-text` |
+| accent | Widget | declared, and the widget reads `--sl-widget-accent` + `--sl-widget-accent-contrast` |
+| textAlign | Widget | declared, and the widget uses `text-align: inherit` |
+| anything else (shapes, button style…) | Widget | the widget's own `settings` schema — not host styling |
+
+**Variables the host sets** on the box (only the ones chosen):
+
+```css
+--sl-widget-accent            /* hex */
+--sl-widget-accent-contrast   /* readable text on the accent: #111111 or #ffffff */
+--sl-widget-text              /* hex */
+--sl-widget-radius            /* e.g. 12px — use it on your own rounded elements */
+```
+
+**Widget rules**
+
+1. **Transparent by default** — the root element has no background, border or padding of its own.
+   Need a card look? Declare `background: "own"` and make the card one of the widget's own settings.
+2. **Read the variables with fallbacks** to the theme tokens, for every colour that should follow:
+   `background: var(--sl-widget-accent, var(--sl-color-accent));`
+   `color: var(--sl-widget-accent-contrast, var(--sl-color-on-accent));`
+   `color: var(--sl-widget-text, inherit);`
+3. **Inherit text** — `color: inherit` / `text-align: inherit` on headings and messages if you declare
+   `text` / `textAlign`.
+4. **No hardcoded colours** for buttons, links or focus rings — accent + accent-contrast.
+5. **No global CSS** — ship scoped styles; nothing may affect elements outside the widget's box.
+
+**Hosts** use the SDK helpers so every host behaves the same:
+
+```ts
+import { widgetStyleControls, widgetStyleVars } from '@proveanything/smartlinks'
+
+const controls = widgetStyleControls(component.styleSupport)   // which controls to show
+const vars = widgetStyleVars({ accent, text, radius }, component.styleSupport) // CSS vars for the box
+```
+
+Conformance checklist (per widget, in the host's editor preview and live): unstyled looks as before
+(light and dark); Background fills the whole box (unless `own`); Text recolours all text; Accent
+recolours every button, link, focus ring and active state, and labels stay readable (try yellow and
+near-black); undeclared controls are absent; padding 0 and 40 don't clip or double up; radius 0 and
+32 with a border clip cleanly; width 50% at each alignment; scale 60% and 130% don't overlap
+neighbours; dialogs opened from the widget are unaffected; nothing outside the box changes.
+
 ---
 
 ## Best Practices

package/openapi.yaml

@@ -74,8 +74,6 @@ tags:
     description: Product facet querying and aggregation.
   - name: form
     description: Form definitions and submissions.
-  - name: functions
-    description: functions API
   - name: integrations
     description: Third-party integration flows and imports.
   - name: interactions
@@ -10024,26 +10022,6 @@ paths:
           description: Unauthorized
         404:
           description: Not found
-  /functions:
-    get:
-      tags:
-        - functions
-      summary: List the public functions available for a collection (discovery).
-      operationId: functions_list
-      security: []
-      responses:
-        200:
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/FunctionListResponse"
-        400:
-          description: Bad request
-        401:
-          description: Unauthorized
-        404:
-          description: Not found
   /platform/location:
     post:
       tags:
@@ -11360,6 +11338,40 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/comm/signup:
+    post:
+      tags:
+        - comms
+      summary: "Public: sign an email address up for topics (a newsletter, updates) — works signed out."
+      operationId: comms_signup
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
   /public/collection/{collectionId}/comm/sms/register:
     post:
       tags:
@@ -18888,8 +18900,24 @@ components:
         settings:
           type: object
           additionalProperties: true
+        styleSupport:
+          $ref: "#/components/schemas/WidgetStyleSupport"
       required:
         - name
+    WidgetStyleSupport:
+      type: object
+      properties:
+        accent:
+          type: boolean
+        text:
+          type: boolean
+        textAlign:
+          type: boolean
+        background:
+          type: string
+          enum:
+            - transparent
+            - own
     AppManifestWidgets:
       type: object
       properties:
@@ -23526,7 +23554,6 @@ components:
           type: object
           additionalProperties: true
       required:
-        - contactId
         - endpoint
         - keys
     CommsSettings:
@@ -23618,8 +23645,6 @@ components:
           $ref: "#/components/schemas/BroadcastChannel"
         token:
           type: string
-      required:
-        - contactId
     UnsubscribeResponse:
       type: object
       properties:
@@ -23628,6 +23653,27 @@ components:
           additionalProperties: true
       required:
         - ok
+    CommsSignupRequest:
+      type: object
+      properties:
+        email:
+          type: string
+        topics:
+          type: array
+          items:
+            type: string
+        firstName:
+          type: string
+      required:
+        - email
+    CommsSignupResponse:
+      type: object
+      properties:
+        ok:
+          type: object
+          additionalProperties: true
+      required:
+        - ok
     CommsConsentUpsertRequest:
       type: object
       properties:
@@ -23641,8 +23687,6 @@ components:
             type: boolean
         topicsByChannel:
           $ref: "#/components/schemas/BroadcastChannel"
-      required:
-        - contactId
     CommsPreferencesUpsertRequest:
       type: object
       properties:
@@ -23659,8 +23703,6 @@ components:
             type: boolean
         topicsByChannel:
           $ref: "#/components/schemas/BroadcastChannel"
-      required:
-        - contactId
     CommsSubscribeRequest:
       type: object
       properties:
@@ -23674,7 +23716,6 @@ components:
         source:
           type: string
       required:
-        - contactId
         - subject
         - subscribe
     CommsSubscribeResponse:
@@ -23697,7 +23738,6 @@ components:
         productId:
           type: string
       required:
-        - contactId
         - subjectType
         - subjectId
     CommsSubscriptionCheckResponse:
@@ -23715,8 +23755,6 @@ components:
           type: string
         type:
           $ref: "#/components/schemas/BroadcastChannel"
-      required:
-        - contactId
     CommsListMethodsResponse:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.47",
+  "version": "2.0.49",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",