@proveanything/smartlinks 1.3.42 → 1.3.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/dist/docs/API_SUMMARY.md +4 -1
  2. package/dist/docs/liquid-templates.md +158 -88
  3. package/dist/types/collection.d.ts +5 -0
  4. package/docs/API_SUMMARY.md +4 -1
  5. package/docs/liquid-templates.md +158 -88
  6. package/package.json +1 -1
package/dist/docs/API_SUMMARY.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Smartlinks API Summary
2
2
 
3
- Version: 1.3.42 | Generated: 2026-02-19T07:40:37.858Z
3
+ Version: 1.3.45 | Generated: 2026-02-19T14:43:39.335Z
4
4
 
5
5
  This is a concise summary of all available API functions and types.
6
6
 
@@ -1504,8 +1504,11 @@ interface Collection {
1504
1504
  redirectUrl?: string // Whether the collection has a custom domain
1505
1505
  shortId: string, // The shortId of this collection
1506
1506
  dark?: boolean // if dark mode is enabled for this collection
1507
+ primaryColor?: string
1508
+ secondaryColor?: string
1507
1509
  portalUrl?: string // URL for the collection's portal (if applicable)
1508
1510
  allowAutoGenerateClaims?: boolean
1511
+ defaultAuthKitId: string // default auth kit for this collection, used for auth
1509
1512
  }
1510
1513
  ```
1511
1514
 
package/dist/docs/liquid-templates.md CHANGED
@@ -41,23 +41,43 @@ A **Collection** represents a top-level business, brand, or organization. All pr
41
41
  | `collection.id` | string | Unique identifier |
42
42
  | `collection.title` | string | Display title of the collection |
43
43
  | `collection.description` | string | Description text |
44
- | `collection.slug` | string | URL-friendly identifier |
45
- | `collection.logoUrl` | string | URL to the collection's logo image |
46
- | `collection.websiteUrl` | string | Primary website URL |
47
- | `collection.metadata` | object | Custom key-value metadata |
48
- | `collection.createdAt` | datetime | When the collection was created |
49
- | `collection.updatedAt` | datetime | When the collection was last updated |
44
+ | `collection.shortId` | string | Short identifier for the collection |
45
+ | `collection.logoImage.url` | string | URL to the collection's logo image |
46
+ | `collection.logoImage.thumbnails.x100` | string | 100px thumbnail |
47
+ | `collection.logoImage.thumbnails.x200` | string | 200px thumbnail |
48
+ | `collection.logoImage.thumbnails.x512` | string | 512px thumbnail |
49
+ | `collection.headerImage.url` | string | URL to collection header/hero image |
50
+ | `collection.headerImage.thumbnails.*` | string | Header image thumbnails (x100, x200, x512) |
51
+ | `collection.loaderImage.url` | string | URL to collection loader image |
52
+ | `collection.primaryColor` | string | Primary theme color (hex code) |
53
+ | `collection.secondaryColor` | string | Secondary theme color (hex code) |
54
+ | `collection.dark` | boolean | Whether dark mode is enabled |
55
+ | `collection.portalUrl` | string | URL for the collection's portal |
56
+ | `collection.redirectUrl` | string | Custom domain redirect URL |
57
+ | `collection.roles` | object | User roles mapping (userId → role) |
58
+ | `collection.groupTags` | array | Array of group tag names |
59
+ | `collection.languages` | array | Array of supported language objects |
60
+ | `collection.defaultAuthKitId` | string | Default auth kit ID |
61
+ | `collection.allowAutoGenerateClaims` | boolean | Allow claiming without proof ID |
50
62
 
51
63
  #### Example Usage
52
64
 
53
65
  ```liquid
54
- Welcome to {{ collection.name }}!
66
+ Welcome to {{ collection.title }}!
55
67
 
56
- {% if collection.websiteUrl %}
57
- Visit us at {{ collection.websiteUrl }}
68
+ {% if collection.portalUrl %}
69
+ Visit our portal at {{ collection.portalUrl }}
58
70
  {% endif %}
59
71
 
60
- <img src="{{ collection.logoUrl }}" alt="{{ collection.name }} logo" />
72
+ {% if collection.logoImage %}
73
+ <img src="{{ collection.logoImage.url }}" alt="{{ collection.title }} logo" />
74
+ <!-- Or use a thumbnail: -->
75
+ <img src="{{ collection.logoImage.thumbnails.x200 }}" alt="{{ collection.title }} logo" />
76
+ {% endif %}
77
+
78
+ {% if collection.dark %}
79
+ <!-- Dark mode is enabled -->
80
+ {% endif %}
61
81
  ```
62
82
 
63
83
  ---
@@ -70,31 +90,44 @@ A **Product** represents a type or definition of a physical or digital item. Pro
70
90
  |-------|------|-------------|
71
91
  | `product.id` | string | Unique identifier |
72
92
  | `product.name` | string | Product name |
93
+ | `product.collectionId` | string | ID of the parent collection |
73
94
  | `product.description` | string | Product description |
74
- | `product.sku` | string | Stock keeping unit |
75
- | `product.slug` | string | URL-friendly identifier |
76
- | `product.imageUrl` | string | Primary product image URL |
77
- | `product.images` | array | Array of image URLs |
78
- | `product.category` | string | Product category |
79
- | `product.tags` | array | Array of tag strings |
80
- | `product.metadata` | object | Custom key-value metadata |
81
- | `product.createdAt` | datetime | When the product was created |
82
- | `product.updatedAt` | datetime | When the product was last updated |
95
+ | `product.gtin` | string | Global Trade Item Number |
96
+ | `product.type` | string | Product type from standard types |
97
+ | `product.heroImage.url` | string | Primary product image URL |
98
+ | `product.heroImage.thumbnails.x100` | string | 100px thumbnail |
99
+ | `product.heroImage.thumbnails.x200` | string | 200px thumbnail |
100
+ | `product.heroImage.thumbnails.x512` | string | 512px thumbnail |
101
+ | `product.tags` | object | Tag map with boolean values |
102
+ | `product.data` | object | Flexible key-value data map |
103
+ | `product.admin` | object | Admin-only configuration |
104
+ | `product.admin.allowAutoGenerateClaims` | boolean | Allow claiming without proof ID |
105
+ | `product.admin.lastSerialId` | number | Last generated serial ID |
83
106
 
84
107
  #### Example Usage
85
108
 
86
109
  ```liquid
87
- Your {{ product.name }} (SKU: {{ product.sku }})
110
+ Your {{ product.name }}
88
111
 
89
112
  {{ product.description }}
90
113
 
91
- {% if product.tags.size > 0 %}
92
- Tags: {{ product.tags | join: ", " }}
114
+ {% if product.gtin %}
115
+ GTIN: {{ product.gtin }}
93
116
  {% endif %}
94
117
 
95
- {% for image in product.images %}
96
- <img src="{{ image }}" alt="{{ product.name }}" />
97
- {% endfor %}
118
+ {% if product.heroImage %}
119
+ <img src="{{ product.heroImage.url }}" alt="{{ product.name }}" />
120
+ <!-- Or use a thumbnail: -->
121
+ <img src="{{ product.heroImage.thumbnails.x512 }}" alt="{{ product.name }}" />
122
+ {% endif %}
123
+
124
+ {% if product.tags.premium %}
125
+ 🌟 Premium Product
126
+ {% endif %}
127
+
128
+ {% if product.data.warranty_years %}
129
+ Warranty: {{ product.data.warranty_years }} years
130
+ {% endif %}
98
131
  ```
99
132
 
100
133
  ---
@@ -106,34 +139,50 @@ A **Proof** is a specific instance of a product—think of it as a unique digita
106
139
  | Field | Type | Description |
107
140
  |-------|------|-------------|
108
141
  | `proof.id` | string | Unique identifier |
109
- | `proof.serialNumber` | string | Human-readable serial number |
110
- | `proof.claimed` | boolean | Whether the proof has been claimed |
111
- | `proof.claimedAt` | datetime | When the proof was claimed |
112
- | `proof.claimedBy` | string | User ID of the claimer |
113
- | `proof.status` | string | Current status (e.g., "active", "transferred") |
114
- | `proof.nfcTagId` | string | Associated NFC tag ID (if applicable) |
115
- | `proof.qrCode` | string | QR code identifier |
116
- | `proof.shortCode` | string | Short code for easy lookup |
117
- | `proof.metadata` | object | Custom key-value metadata |
142
+ | `proof.collectionId` | string | ID of the parent collection |
143
+ | `proof.productId` | string | ID of the associated product |
144
+ | `proof.tokenId` | string | Unique token identifier |
145
+ | `proof.userId` | string | User ID of the owner |
146
+ | `proof.claimable` | boolean | Whether the proof can be claimed |
147
+ | `proof.virtual` | boolean | Whether this is a virtual proof |
148
+ | `proof.values` | object | Arbitrary key-value pairs for proof data |
118
149
  | `proof.createdAt` | datetime | When the proof was created |
119
- | `proof.updatedAt` | datetime | When the proof was last updated |
150
+
151
+ **Note**: Proof `values` object can contain any custom fields. Common examples:
152
+ - `proof.values.serialNumber` - Serial number
153
+ - `proof.values.claimedAt` - Claim timestamp
154
+ - `proof.values.status` - Current status
155
+ - `proof.values.warrantyExpiry` - Warranty expiration
120
156
 
121
157
  #### Example Usage
122
158
 
123
159
  ```liquid
124
160
  Proof of Authenticity
125
161
 
126
- Serial Number: {{ proof.serialNumber }}
127
- Status: {{ proof.status }}
162
+ {% if proof.values.serialNumber %}
163
+ Serial Number: {{ proof.values.serialNumber }}
164
+ {% endif %}
128
165
 
129
- {% if proof.claimed %}
130
- Claimed on: {{ proof.claimedAt | date: "%B %d, %Y at %H:%M" }}
166
+ {% if proof.values.status %}
167
+ Status: {{ proof.values.status }}
168
+ {% endif %}
169
+
170
+ {% if proof.claimable %}
171
+ This item is available to claim.
131
172
  {% else %}
132
- This item has not been claimed yet.
173
+ This item has been claimed.
133
174
  {% endif %}
134
175
 
135
- {% if proof.metadata.warrantyExpiry %}
136
- Warranty expires: {{ proof.metadata.warrantyExpiry | date: "%B %d, %Y" }}
176
+ {% if proof.virtual %}
177
+ 🌐 Digital Product
178
+ {% endif %}
179
+
180
+ {% if proof.values.claimedAt %}
181
+ Claimed on: {{ proof.values.claimedAt | date: "%B %d, %Y at %H:%M" }}
182
+ {% endif %}
183
+
184
+ {% if proof.values.warrantyExpiry %}
185
+ Warranty expires: {{ proof.values.warrantyExpiry | date: "%B %d, %Y" }}
137
186
  {% endif %}
138
187
  ```
139
188
 
@@ -145,25 +194,32 @@ A **Contact** represents a customer or user in the system. Contacts are associat
145
194
 
146
195
  | Field | Type | Description |
147
196
  |-------|------|-------------|
148
- | `contact.id` | string | Unique identifier |
149
- | `contact.email` | string | Email address |
150
- | `contact.name` | string | Full name |
197
+ | `contact.contactId` | string | Unique identifier |
198
+ | `contact.orgId` | string | Organization/collection ID |
199
+ | `contact.userId` | string | Linked user ID (if authenticated) |
200
+ | `contact.email` | string | Primary email address |
201
+ | `contact.phone` | string | Primary phone number |
202
+ | `contact.emails` | array | Array of all email addresses |
203
+ | `contact.phones` | array | Array of all phone numbers |
151
204
  | `contact.firstName` | string | First name |
152
205
  | `contact.lastName` | string | Last name |
153
- | `contact.phone` | string | Phone number |
206
+ | `contact.displayName` | string | Display name |
207
+ | `contact.company` | string | Company name |
208
+ | `contact.avatarUrl` | string | Profile picture URL |
154
209
  | `contact.locale` | string | Preferred language/locale (e.g., "en", "de") |
155
210
  | `contact.timezone` | string | Preferred timezone |
156
- | `contact.avatarUrl` | string | Profile picture URL |
157
- | `contact.metadata` | object | Custom key-value metadata |
158
211
  | `contact.tags` | array | Array of tag strings for segmentation |
212
+ | `contact.source` | string | How the contact was created |
213
+ | `contact.notes` | string | Admin notes |
214
+ | `contact.externalIds` | object | External system IDs |
215
+ | `contact.customFields` | object | Custom key-value data |
159
216
  | `contact.createdAt` | datetime | When the contact was created |
160
217
  | `contact.updatedAt` | datetime | When the contact was last updated |
161
- | `contact.lastSeenAt` | datetime | Last activity timestamp |
162
218
 
163
219
  #### Example Usage
164
220
 
165
221
  ```liquid
166
- Hi {{ contact.firstName | default: contact.name | default: "there" }},
222
+ Hi {{ contact.firstName | default: contact.displayName | default: "there" }},
167
223
 
168
224
  {% if contact.locale == "de" %}
169
225
  Willkommen!
@@ -176,6 +232,14 @@ Welcome!
176
232
  {% if contact.phone %}
177
233
  We'll send updates to {{ contact.phone }}.
178
234
  {% endif %}
235
+
236
+ {% if contact.company %}
237
+ Company: {{ contact.company }}
238
+ {% endif %}
239
+
240
+ {% if contact.customFields.vip %}
241
+ 🌟 VIP Customer
242
+ {% endif %}
179
243
  ```
180
244
 
181
245
  ---
@@ -186,20 +250,18 @@ A **User** represents an authenticated account in the system. This is typically
186
250
 
187
251
  | Field | Type | Description |
188
252
  |-------|------|-------------|
189
- | `user.id` | string | Unique identifier |
253
+ | `user.uid` | string | Unique identifier |
190
254
  | `user.email` | string | Email address |
191
- | `user.name` | string | Display name |
192
- | `user.admin` | boolean | Whether user has admin privileges |
193
- | `user.avatarUrl` | string | Profile picture URL |
194
- | `user.createdAt` | datetime | Account creation date |
255
+ | `user.displayName` | string | Display name |
256
+ | `user.accountData` | object | Account-specific data and settings |
195
257
 
196
258
  #### Example Usage
197
259
 
198
260
  ```liquid
199
- Logged in as: {{ user.name }} ({{ user.email }})
261
+ Logged in as: {{ user.displayName }} ({{ user.email }})
200
262
 
201
- {% if user.admin %}
202
- 🔐 You have administrator access.
263
+ {% if user.accountData.preferences.notifications %}
264
+ Notifications are enabled.
203
265
  {% endif %}
204
266
  ```
205
267
 
@@ -212,26 +274,33 @@ An **Attestation** is flexible data attached to a specific proof. It's used to s
212
274
  | Field | Type | Description |
213
275
  |-------|------|-------------|
214
276
  | `attestation.id` | string | Unique identifier |
215
- | `attestation.type` | string | Attestation type (app-defined) |
216
- | `attestation.data` | object | The attestation payload (varies by type) |
217
- | `attestation.createdBy` | string | User ID who created it |
277
+ | `attestation.public` | object | Public attestation data (varies by type) |
278
+ | `attestation.private` | object | Private attestation data (varies by type) |
279
+ | `attestation.proof` | object | Associated proof reference/data |
218
280
  | `attestation.createdAt` | datetime | When the attestation was created |
219
281
  | `attestation.updatedAt` | datetime | When the attestation was last updated |
220
282
 
283
+ **Note**: The `public` and `private` objects contain custom fields based on your use case.
284
+
221
285
  #### Example Usage
222
286
 
223
287
  ```liquid
224
- {% if attestation.type == "warranty_registration" %}
288
+ {% if attestation.public.type == "warranty_registration" %}
225
289
  Warranty Registration Details:
226
290
  - Registered: {{ attestation.createdAt | date: "%B %d, %Y" }}
227
- - Purchase Date: {{ attestation.data.purchaseDate }}
228
- - Store: {{ attestation.data.storeName }}
291
+ - Purchase Date: {{ attestation.public.purchaseDate }}
292
+ - Store: {{ attestation.public.storeName }}
293
+ {% endif %}
294
+
295
+ {% if attestation.public.type == "tasting_note" %}
296
+ 🍷 Tasting Note:
297
+ "{{ attestation.public.notes }}"
298
+ Rating: {{ attestation.public.rating }}/5
229
299
  {% endif %}
230
300
 
231
- {% if attestation.type == "tasting_note" %}
232
- 🍷 Tasting Note by {{ attestation.data.author }}:
233
- "{{ attestation.data.notes }}"
234
- Rating: {{ attestation.data.rating }}/5
301
+ {% if attestation.private.internalNotes %}
302
+ <!-- Private data only visible to admins -->
303
+ Notes: {{ attestation.private.internalNotes }}
235
304
  {% endif %}
236
305
  ```
237
306
 
@@ -357,37 +426,37 @@ Loop variables:
357
426
  ```liquid
358
427
  Subject: Your {{ product.name }} has been registered!
359
428
 
360
- Hi {{ contact.firstName | default: "there" }},
429
+ Hi {{ contact.firstName | default: contact.displayName | default: "there" }},
361
430
 
362
- Great news! Your {{ product.name }} (Serial: {{ proof.serialNumber }})
431
+ Great news! Your {{ product.name }}{% if proof.values.serialNumber %} (Serial: {{ proof.values.serialNumber }}){% endif %}
363
432
  has been successfully registered to your account.
364
433
 
365
- {% if product.metadata.warrantyYears %}
366
- Your warranty is valid for {{ product.metadata.warrantyYears }} years
434
+ {% if product.data.warranty_years %}
435
+ Your warranty is valid for {{ product.data.warranty_years }} years
367
436
  from the date of purchase.
368
437
  {% endif %}
369
438
 
370
- If you have any questions, please contact {{ collection.name }} support.
439
+ If you have any questions, please contact {{ collection.title }} support.
371
440
 
372
441
  Best regards,
373
- The {{ collection.name }} Team
442
+ The {{ collection.title }} Team
374
443
  ```
375
444
 
376
445
  ### Notification Messages
377
446
 
378
447
  ```liquid
379
448
  🎉 {{ contact.firstName }}, your {{ product.name }} is now verified!
380
- Proof ID: {{ proof.shortCode }}
449
+ {% if proof.values.shortCode %}Proof ID: {{ proof.values.shortCode }}{% endif %}
381
450
  ```
382
451
 
383
452
  ### Dynamic Content Blocks
384
453
 
385
454
  ```liquid
386
- {% if proof.metadata.tier == "gold" %}
455
+ {% if proof.values.tier == "gold" %}
387
456
  <div class="gold-benefits">
388
457
  As a Gold member, you get exclusive access to...
389
458
  </div>
390
- {% elsif proof.metadata.tier == "silver" %}
459
+ {% elsif proof.values.tier == "silver" %}
391
460
  <div class="silver-benefits">
392
461
  Your Silver membership includes...
393
462
  </div>
@@ -413,18 +482,19 @@ Proof ID: {{ proof.shortCode }}
413
482
 
414
483
  ## Accessing Nested Data
415
484
 
416
- Use dot notation to access nested fields in metadata or data objects:
485
+ Use dot notation to access nested fields in data objects:
417
486
 
418
487
  ```liquid
419
- {{ product.metadata.manufacturer }}
420
- {{ attestation.data.warranty.expiryDate }}
421
- {{ collection.metadata.social.twitter }}
488
+ {{ product.data.manufacturer }}
489
+ {{ attestation.public.warranty.expiryDate }}
490
+ {{ contact.customFields.vip_level }}
491
+ {{ proof.values.serialNumber }}
422
492
  ```
423
493
 
424
494
  For dynamic keys, you may need to use bracket notation (if supported):
425
495
 
426
496
  ```liquid
427
- {{ product.metadata["custom-field"] }}
497
+ {{ product.data["custom-field"] }}
428
498
  ```
429
499
 
430
500
  ---
@@ -433,29 +503,29 @@ For dynamic keys, you may need to use bracket notation (if supported):
433
503
 
434
504
  1. **Always use `default` filter** for optional fields to avoid blank output:
435
505
  ```liquid
436
- {{ contact.name | default: "Valued Customer" }}
506
+ {{ contact.displayName | default: contact.firstName | default: "Valued Customer" }}
437
507
  ```
438
508
 
439
509
  2. **Escape user-generated content** when outputting as HTML:
440
510
  ```liquid
441
- {{ attestation.data.userNotes | escape }}
511
+ {{ attestation.public.userNotes | escape }}
442
512
  ```
443
513
 
444
514
  3. **Check for existence** before accessing nested data:
445
515
  ```liquid
446
- {% if proof.metadata.warranty %}
447
- Warranty: {{ proof.metadata.warranty.type }}
516
+ {% if proof.values.warranty %}
517
+ Warranty: {{ proof.values.warranty.type }}
448
518
  {% endif %}
449
519
  ```
450
520
 
451
521
  4. **Use meaningful fallbacks** for a better user experience:
452
522
  ```liquid
453
- Hi {{ contact.firstName | default: contact.name | default: "there" }},
523
+ Hi {{ contact.firstName | default: contact.displayName | default: "there" }},
454
524
  ```
455
525
 
456
526
  5. **Format dates appropriately** for the user's locale:
457
527
  ```liquid
458
- {{ proof.claimedAt | date: "%d %B %Y" }}
528
+ {{ proof.createdAt | date: "%d %B %Y" }}
459
529
  ```
460
530
 
461
531
  ---
package/dist/types/collection.d.ts CHANGED
@@ -62,9 +62,14 @@ export interface Collection {
62
62
  shortId: string;
63
63
  /** if dark mode is enabled for this collection */
64
64
  dark?: boolean;
65
+ /** Primary theme color */
66
+ primaryColor?: string;
67
+ /** Secondary theme color */
68
+ secondaryColor?: string;
65
69
  portalUrl?: string;
66
70
  /** Allow users to claim products without providing a proof ID (auto-generates serial on-demand) */
67
71
  allowAutoGenerateClaims?: boolean;
72
+ defaultAuthKitId: string;
68
73
  }
69
74
  export type CollectionResponse = Collection;
70
75
  export type CollectionCreateRequest = Omit<Collection, 'id' | 'shortId'>;
package/docs/API_SUMMARY.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Smartlinks API Summary
2
2
 
3
- Version: 1.3.42 | Generated: 2026-02-19T07:40:37.858Z
3
+ Version: 1.3.45 | Generated: 2026-02-19T14:43:39.335Z
4
4
 
5
5
  This is a concise summary of all available API functions and types.
6
6
 
@@ -1504,8 +1504,11 @@ interface Collection {
1504
1504
  redirectUrl?: string // Whether the collection has a custom domain
1505
1505
  shortId: string, // The shortId of this collection
1506
1506
  dark?: boolean // if dark mode is enabled for this collection
1507
+ primaryColor?: string
1508
+ secondaryColor?: string
1507
1509
  portalUrl?: string // URL for the collection's portal (if applicable)
1508
1510
  allowAutoGenerateClaims?: boolean
1511
+ defaultAuthKitId: string // default auth kit for this collection, used for auth
1509
1512
  }
1510
1513
  ```
1511
1514
 
package/docs/liquid-templates.md CHANGED
@@ -41,23 +41,43 @@ A **Collection** represents a top-level business, brand, or organization. All pr
41
41
  | `collection.id` | string | Unique identifier |
42
42
  | `collection.title` | string | Display title of the collection |
43
43
  | `collection.description` | string | Description text |
44
- | `collection.slug` | string | URL-friendly identifier |
45
- | `collection.logoUrl` | string | URL to the collection's logo image |
46
- | `collection.websiteUrl` | string | Primary website URL |
47
- | `collection.metadata` | object | Custom key-value metadata |
48
- | `collection.createdAt` | datetime | When the collection was created |
49
- | `collection.updatedAt` | datetime | When the collection was last updated |
44
+ | `collection.shortId` | string | Short identifier for the collection |
45
+ | `collection.logoImage.url` | string | URL to the collection's logo image |
46
+ | `collection.logoImage.thumbnails.x100` | string | 100px thumbnail |
47
+ | `collection.logoImage.thumbnails.x200` | string | 200px thumbnail |
48
+ | `collection.logoImage.thumbnails.x512` | string | 512px thumbnail |
49
+ | `collection.headerImage.url` | string | URL to collection header/hero image |
50
+ | `collection.headerImage.thumbnails.*` | string | Header image thumbnails (x100, x200, x512) |
51
+ | `collection.loaderImage.url` | string | URL to collection loader image |
52
+ | `collection.primaryColor` | string | Primary theme color (hex code) |
53
+ | `collection.secondaryColor` | string | Secondary theme color (hex code) |
54
+ | `collection.dark` | boolean | Whether dark mode is enabled |
55
+ | `collection.portalUrl` | string | URL for the collection's portal |
56
+ | `collection.redirectUrl` | string | Custom domain redirect URL |
57
+ | `collection.roles` | object | User roles mapping (userId → role) |
58
+ | `collection.groupTags` | array | Array of group tag names |
59
+ | `collection.languages` | array | Array of supported language objects |
60
+ | `collection.defaultAuthKitId` | string | Default auth kit ID |
61
+ | `collection.allowAutoGenerateClaims` | boolean | Allow claiming without proof ID |
50
62
 
51
63
  #### Example Usage
52
64
 
53
65
  ```liquid
54
- Welcome to {{ collection.name }}!
66
+ Welcome to {{ collection.title }}!
55
67
 
56
- {% if collection.websiteUrl %}
57
- Visit us at {{ collection.websiteUrl }}
68
+ {% if collection.portalUrl %}
69
+ Visit our portal at {{ collection.portalUrl }}
58
70
  {% endif %}
59
71
 
60
- <img src="{{ collection.logoUrl }}" alt="{{ collection.name }} logo" />
72
+ {% if collection.logoImage %}
73
+ <img src="{{ collection.logoImage.url }}" alt="{{ collection.title }} logo" />
74
+ <!-- Or use a thumbnail: -->
75
+ <img src="{{ collection.logoImage.thumbnails.x200 }}" alt="{{ collection.title }} logo" />
76
+ {% endif %}
77
+
78
+ {% if collection.dark %}
79
+ <!-- Dark mode is enabled -->
80
+ {% endif %}
61
81
  ```
62
82
 
63
83
  ---
@@ -70,31 +90,44 @@ A **Product** represents a type or definition of a physical or digital item. Pro
70
90
  |-------|------|-------------|
71
91
  | `product.id` | string | Unique identifier |
72
92
  | `product.name` | string | Product name |
93
+ | `product.collectionId` | string | ID of the parent collection |
73
94
  | `product.description` | string | Product description |
74
- | `product.sku` | string | Stock keeping unit |
75
- | `product.slug` | string | URL-friendly identifier |
76
- | `product.imageUrl` | string | Primary product image URL |
77
- | `product.images` | array | Array of image URLs |
78
- | `product.category` | string | Product category |
79
- | `product.tags` | array | Array of tag strings |
80
- | `product.metadata` | object | Custom key-value metadata |
81
- | `product.createdAt` | datetime | When the product was created |
82
- | `product.updatedAt` | datetime | When the product was last updated |
95
+ | `product.gtin` | string | Global Trade Item Number |
96
+ | `product.type` | string | Product type from standard types |
97
+ | `product.heroImage.url` | string | Primary product image URL |
98
+ | `product.heroImage.thumbnails.x100` | string | 100px thumbnail |
99
+ | `product.heroImage.thumbnails.x200` | string | 200px thumbnail |
100
+ | `product.heroImage.thumbnails.x512` | string | 512px thumbnail |
101
+ | `product.tags` | object | Tag map with boolean values |
102
+ | `product.data` | object | Flexible key-value data map |
103
+ | `product.admin` | object | Admin-only configuration |
104
+ | `product.admin.allowAutoGenerateClaims` | boolean | Allow claiming without proof ID |
105
+ | `product.admin.lastSerialId` | number | Last generated serial ID |
83
106
 
84
107
  #### Example Usage
85
108
 
86
109
  ```liquid
87
- Your {{ product.name }} (SKU: {{ product.sku }})
110
+ Your {{ product.name }}
88
111
 
89
112
  {{ product.description }}
90
113
 
91
- {% if product.tags.size > 0 %}
92
- Tags: {{ product.tags | join: ", " }}
114
+ {% if product.gtin %}
115
+ GTIN: {{ product.gtin }}
93
116
  {% endif %}
94
117
 
95
- {% for image in product.images %}
96
- <img src="{{ image }}" alt="{{ product.name }}" />
97
- {% endfor %}
118
+ {% if product.heroImage %}
119
+ <img src="{{ product.heroImage.url }}" alt="{{ product.name }}" />
120
+ <!-- Or use a thumbnail: -->
121
+ <img src="{{ product.heroImage.thumbnails.x512 }}" alt="{{ product.name }}" />
122
+ {% endif %}
123
+
124
+ {% if product.tags.premium %}
125
+ 🌟 Premium Product
126
+ {% endif %}
127
+
128
+ {% if product.data.warranty_years %}
129
+ Warranty: {{ product.data.warranty_years }} years
130
+ {% endif %}
98
131
  ```
99
132
 
100
133
  ---
@@ -106,34 +139,50 @@ A **Proof** is a specific instance of a product—think of it as a unique digita
106
139
  | Field | Type | Description |
107
140
  |-------|------|-------------|
108
141
  | `proof.id` | string | Unique identifier |
109
- | `proof.serialNumber` | string | Human-readable serial number |
110
- | `proof.claimed` | boolean | Whether the proof has been claimed |
111
- | `proof.claimedAt` | datetime | When the proof was claimed |
112
- | `proof.claimedBy` | string | User ID of the claimer |
113
- | `proof.status` | string | Current status (e.g., "active", "transferred") |
114
- | `proof.nfcTagId` | string | Associated NFC tag ID (if applicable) |
115
- | `proof.qrCode` | string | QR code identifier |
116
- | `proof.shortCode` | string | Short code for easy lookup |
117
- | `proof.metadata` | object | Custom key-value metadata |
142
+ | `proof.collectionId` | string | ID of the parent collection |
143
+ | `proof.productId` | string | ID of the associated product |
144
+ | `proof.tokenId` | string | Unique token identifier |
145
+ | `proof.userId` | string | User ID of the owner |
146
+ | `proof.claimable` | boolean | Whether the proof can be claimed |
147
+ | `proof.virtual` | boolean | Whether this is a virtual proof |
148
+ | `proof.values` | object | Arbitrary key-value pairs for proof data |
118
149
  | `proof.createdAt` | datetime | When the proof was created |
119
- | `proof.updatedAt` | datetime | When the proof was last updated |
150
+
151
+ **Note**: Proof `values` object can contain any custom fields. Common examples:
152
+ - `proof.values.serialNumber` - Serial number
153
+ - `proof.values.claimedAt` - Claim timestamp
154
+ - `proof.values.status` - Current status
155
+ - `proof.values.warrantyExpiry` - Warranty expiration
120
156
 
121
157
  #### Example Usage
122
158
 
123
159
  ```liquid
124
160
  Proof of Authenticity
125
161
 
126
- Serial Number: {{ proof.serialNumber }}
127
- Status: {{ proof.status }}
162
+ {% if proof.values.serialNumber %}
163
+ Serial Number: {{ proof.values.serialNumber }}
164
+ {% endif %}
128
165
 
129
- {% if proof.claimed %}
130
- Claimed on: {{ proof.claimedAt | date: "%B %d, %Y at %H:%M" }}
166
+ {% if proof.values.status %}
167
+ Status: {{ proof.values.status }}
168
+ {% endif %}
169
+
170
+ {% if proof.claimable %}
171
+ This item is available to claim.
131
172
  {% else %}
132
- This item has not been claimed yet.
173
+ This item has been claimed.
133
174
  {% endif %}
134
175
 
135
- {% if proof.metadata.warrantyExpiry %}
136
- Warranty expires: {{ proof.metadata.warrantyExpiry | date: "%B %d, %Y" }}
176
+ {% if proof.virtual %}
177
+ 🌐 Digital Product
178
+ {% endif %}
179
+
180
+ {% if proof.values.claimedAt %}
181
+ Claimed on: {{ proof.values.claimedAt | date: "%B %d, %Y at %H:%M" }}
182
+ {% endif %}
183
+
184
+ {% if proof.values.warrantyExpiry %}
185
+ Warranty expires: {{ proof.values.warrantyExpiry | date: "%B %d, %Y" }}
137
186
  {% endif %}
138
187
  ```
139
188
 
@@ -145,25 +194,32 @@ A **Contact** represents a customer or user in the system. Contacts are associat
145
194
 
146
195
  | Field | Type | Description |
147
196
  |-------|------|-------------|
148
- | `contact.id` | string | Unique identifier |
149
- | `contact.email` | string | Email address |
150
- | `contact.name` | string | Full name |
197
+ | `contact.contactId` | string | Unique identifier |
198
+ | `contact.orgId` | string | Organization/collection ID |
199
+ | `contact.userId` | string | Linked user ID (if authenticated) |
200
+ | `contact.email` | string | Primary email address |
201
+ | `contact.phone` | string | Primary phone number |
202
+ | `contact.emails` | array | Array of all email addresses |
203
+ | `contact.phones` | array | Array of all phone numbers |
151
204
  | `contact.firstName` | string | First name |
152
205
  | `contact.lastName` | string | Last name |
153
- | `contact.phone` | string | Phone number |
206
+ | `contact.displayName` | string | Display name |
207
+ | `contact.company` | string | Company name |
208
+ | `contact.avatarUrl` | string | Profile picture URL |
154
209
  | `contact.locale` | string | Preferred language/locale (e.g., "en", "de") |
155
210
  | `contact.timezone` | string | Preferred timezone |
156
- | `contact.avatarUrl` | string | Profile picture URL |
157
- | `contact.metadata` | object | Custom key-value metadata |
158
211
  | `contact.tags` | array | Array of tag strings for segmentation |
212
+ | `contact.source` | string | How the contact was created |
213
+ | `contact.notes` | string | Admin notes |
214
+ | `contact.externalIds` | object | External system IDs |
215
+ | `contact.customFields` | object | Custom key-value data |
159
216
  | `contact.createdAt` | datetime | When the contact was created |
160
217
  | `contact.updatedAt` | datetime | When the contact was last updated |
161
- | `contact.lastSeenAt` | datetime | Last activity timestamp |
162
218
 
163
219
  #### Example Usage
164
220
 
165
221
  ```liquid
166
- Hi {{ contact.firstName | default: contact.name | default: "there" }},
222
+ Hi {{ contact.firstName | default: contact.displayName | default: "there" }},
167
223
 
168
224
  {% if contact.locale == "de" %}
169
225
  Willkommen!
@@ -176,6 +232,14 @@ Welcome!
176
232
  {% if contact.phone %}
177
233
  We'll send updates to {{ contact.phone }}.
178
234
  {% endif %}
235
+
236
+ {% if contact.company %}
237
+ Company: {{ contact.company }}
238
+ {% endif %}
239
+
240
+ {% if contact.customFields.vip %}
241
+ 🌟 VIP Customer
242
+ {% endif %}
179
243
  ```
180
244
 
181
245
  ---
@@ -186,20 +250,18 @@ A **User** represents an authenticated account in the system. This is typically
186
250
 
187
251
  | Field | Type | Description |
188
252
  |-------|------|-------------|
189
- | `user.id` | string | Unique identifier |
253
+ | `user.uid` | string | Unique identifier |
190
254
  | `user.email` | string | Email address |
191
- | `user.name` | string | Display name |
192
- | `user.admin` | boolean | Whether user has admin privileges |
193
- | `user.avatarUrl` | string | Profile picture URL |
194
- | `user.createdAt` | datetime | Account creation date |
255
+ | `user.displayName` | string | Display name |
256
+ | `user.accountData` | object | Account-specific data and settings |
195
257
 
196
258
  #### Example Usage
197
259
 
198
260
  ```liquid
199
- Logged in as: {{ user.name }} ({{ user.email }})
261
+ Logged in as: {{ user.displayName }} ({{ user.email }})
200
262
 
201
- {% if user.admin %}
202
- 🔐 You have administrator access.
263
+ {% if user.accountData.preferences.notifications %}
264
+ Notifications are enabled.
203
265
  {% endif %}
204
266
  ```
205
267
 
@@ -212,26 +274,33 @@ An **Attestation** is flexible data attached to a specific proof. It's used to s
212
274
  | Field | Type | Description |
213
275
  |-------|------|-------------|
214
276
  | `attestation.id` | string | Unique identifier |
215
- | `attestation.type` | string | Attestation type (app-defined) |
216
- | `attestation.data` | object | The attestation payload (varies by type) |
217
- | `attestation.createdBy` | string | User ID who created it |
277
+ | `attestation.public` | object | Public attestation data (varies by type) |
278
+ | `attestation.private` | object | Private attestation data (varies by type) |
279
+ | `attestation.proof` | object | Associated proof reference/data |
218
280
  | `attestation.createdAt` | datetime | When the attestation was created |
219
281
  | `attestation.updatedAt` | datetime | When the attestation was last updated |
220
282
 
283
+ **Note**: The `public` and `private` objects contain custom fields based on your use case.
284
+
221
285
  #### Example Usage
222
286
 
223
287
  ```liquid
224
- {% if attestation.type == "warranty_registration" %}
288
+ {% if attestation.public.type == "warranty_registration" %}
225
289
  Warranty Registration Details:
226
290
  - Registered: {{ attestation.createdAt | date: "%B %d, %Y" }}
227
- - Purchase Date: {{ attestation.data.purchaseDate }}
228
- - Store: {{ attestation.data.storeName }}
291
+ - Purchase Date: {{ attestation.public.purchaseDate }}
292
+ - Store: {{ attestation.public.storeName }}
293
+ {% endif %}
294
+
295
+ {% if attestation.public.type == "tasting_note" %}
296
+ 🍷 Tasting Note:
297
+ "{{ attestation.public.notes }}"
298
+ Rating: {{ attestation.public.rating }}/5
229
299
  {% endif %}
230
300
 
231
- {% if attestation.type == "tasting_note" %}
232
- 🍷 Tasting Note by {{ attestation.data.author }}:
233
- "{{ attestation.data.notes }}"
234
- Rating: {{ attestation.data.rating }}/5
301
+ {% if attestation.private.internalNotes %}
302
+ <!-- Private data only visible to admins -->
303
+ Notes: {{ attestation.private.internalNotes }}
235
304
  {% endif %}
236
305
  ```
237
306
 
@@ -357,37 +426,37 @@ Loop variables:
357
426
  ```liquid
358
427
  Subject: Your {{ product.name }} has been registered!
359
428
 
360
- Hi {{ contact.firstName | default: "there" }},
429
+ Hi {{ contact.firstName | default: contact.displayName | default: "there" }},
361
430
 
362
- Great news! Your {{ product.name }} (Serial: {{ proof.serialNumber }})
431
+ Great news! Your {{ product.name }}{% if proof.values.serialNumber %} (Serial: {{ proof.values.serialNumber }}){% endif %}
363
432
  has been successfully registered to your account.
364
433
 
365
- {% if product.metadata.warrantyYears %}
366
- Your warranty is valid for {{ product.metadata.warrantyYears }} years
434
+ {% if product.data.warranty_years %}
435
+ Your warranty is valid for {{ product.data.warranty_years }} years
367
436
  from the date of purchase.
368
437
  {% endif %}
369
438
 
370
- If you have any questions, please contact {{ collection.name }} support.
439
+ If you have any questions, please contact {{ collection.title }} support.
371
440
 
372
441
  Best regards,
373
- The {{ collection.name }} Team
442
+ The {{ collection.title }} Team
374
443
  ```
375
444
 
376
445
  ### Notification Messages
377
446
 
378
447
  ```liquid
379
448
  🎉 {{ contact.firstName }}, your {{ product.name }} is now verified!
380
- Proof ID: {{ proof.shortCode }}
449
+ {% if proof.values.shortCode %}Proof ID: {{ proof.values.shortCode }}{% endif %}
381
450
  ```
382
451
 
383
452
  ### Dynamic Content Blocks
384
453
 
385
454
  ```liquid
386
- {% if proof.metadata.tier == "gold" %}
455
+ {% if proof.values.tier == "gold" %}
387
456
  <div class="gold-benefits">
388
457
  As a Gold member, you get exclusive access to...
389
458
  </div>
390
- {% elsif proof.metadata.tier == "silver" %}
459
+ {% elsif proof.values.tier == "silver" %}
391
460
  <div class="silver-benefits">
392
461
  Your Silver membership includes...
393
462
  </div>
@@ -413,18 +482,19 @@ Proof ID: {{ proof.shortCode }}
413
482
 
414
483
  ## Accessing Nested Data
415
484
 
416
- Use dot notation to access nested fields in metadata or data objects:
485
+ Use dot notation to access nested fields in data objects:
417
486
 
418
487
  ```liquid
419
- {{ product.metadata.manufacturer }}
420
- {{ attestation.data.warranty.expiryDate }}
421
- {{ collection.metadata.social.twitter }}
488
+ {{ product.data.manufacturer }}
489
+ {{ attestation.public.warranty.expiryDate }}
490
+ {{ contact.customFields.vip_level }}
491
+ {{ proof.values.serialNumber }}
422
492
  ```
423
493
 
424
494
  For dynamic keys, you may need to use bracket notation (if supported):
425
495
 
426
496
  ```liquid
427
- {{ product.metadata["custom-field"] }}
497
+ {{ product.data["custom-field"] }}
428
498
  ```
429
499
 
430
500
  ---
@@ -433,29 +503,29 @@ For dynamic keys, you may need to use bracket notation (if supported):
433
503
 
434
504
  1. **Always use `default` filter** for optional fields to avoid blank output:
435
505
  ```liquid
436
- {{ contact.name | default: "Valued Customer" }}
506
+ {{ contact.displayName | default: contact.firstName | default: "Valued Customer" }}
437
507
  ```
438
508
 
439
509
  2. **Escape user-generated content** when outputting as HTML:
440
510
  ```liquid
441
- {{ attestation.data.userNotes | escape }}
511
+ {{ attestation.public.userNotes | escape }}
442
512
  ```
443
513
 
444
514
  3. **Check for existence** before accessing nested data:
445
515
  ```liquid
446
- {% if proof.metadata.warranty %}
447
- Warranty: {{ proof.metadata.warranty.type }}
516
+ {% if proof.values.warranty %}
517
+ Warranty: {{ proof.values.warranty.type }}
448
518
  {% endif %}
449
519
  ```
450
520
 
451
521
  4. **Use meaningful fallbacks** for a better user experience:
452
522
  ```liquid
453
- Hi {{ contact.firstName | default: contact.name | default: "there" }},
523
+ Hi {{ contact.firstName | default: contact.displayName | default: "there" }},
454
524
  ```
455
525
 
456
526
  5. **Format dates appropriately** for the user's locale:
457
527
  ```liquid
458
- {{ proof.claimedAt | date: "%d %B %Y" }}
528
+ {{ proof.createdAt | date: "%d %B %Y" }}
459
529
  ```
460
530
 
461
531
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proveanything/smartlinks",
3
- "version": "1.3.42",
3
+ "version": "1.3.45",
4
4
  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",