@proveanything/smartlinks 1.15.0 → 1.15.2

package/dist/api/collection.d.ts

@@ -1,4 +1,4 @@
-import { CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, AppsConfigResponse } from "../types/collection";
+import { CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, AppsConfigResponse, DomainTarget, HubAvailabilityResponse } from "../types/collection";
 export declare namespace collection {
     /**
      * Retrieves a single Collection by its ID.
@@ -21,6 +21,74 @@ export declare namespace collection {
      * @returns Promise resolving to a CollectionResponse object
      */
     function getShortId(shortId: string): Promise<CollectionResponse>;
+    /**
+     * Resolve the collection for the current Hub domain (public endpoint).
+     *
+     * The server derives the requesting domain from the request headers
+     * (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is
+     * passed — this is the call a Hub frontend makes on load to find out which
+     * collection it is serving, whether it's reached via `{brand}.mysmartlinks.app`
+     * or a bring-your-own custom domain (e.g. `hub.acme.com`).
+     *
+     * @returns Promise resolving to the CollectionResponse mapped to the domain
+     * @throws ErrorResponse (404) if no collection is mapped to the domain
+     */
+    function getByHub(): Promise<CollectionResponse>;
+    /**
+     * Resolve the collection for an explicit Hub domain (public endpoint).
+     *
+     * Unlike {@link getByHub}, the domain is passed explicitly rather than derived
+     * from request headers — use this for raw/cross-origin calls where the Hub
+     * frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+     *
+     * @param domain – The Hub domain to resolve (custom domain or {brand}.mysmartlinks.app)
+     * @returns Promise resolving to the CollectionResponse mapped to the domain
+     * @throws ErrorResponse (404) if no collection is mapped to the domain
+     */
+    function getByDomain(domain: string): Promise<CollectionResponse>;
+    /**
+     * Check whether a Hub subdomain name is available to claim (admin only).
+     * @param collectionId – Identifier of the collection making the request
+     * @param name – Proposed subdomain prefix (lowercase letters, numbers, hyphens; max 63 chars)
+     * @returns Promise resolving to { available, domain }
+     * @throws ErrorResponse (400) if the name fails validation or is reserved
+     */
+    function checkHubAvailability(collectionId: string, name: string): Promise<HubAvailabilityResponse>;
+    /**
+     * Claim or rename the Hub subdomain for a collection (admin only).
+     *
+     * Maps `{hubName}.mysmartlinks.app` to the collection. If the collection
+     * already had a different hub name, the previous subdomain is released
+     * automatically.
+     *
+     * @param collectionId – Identifier of the collection
+     * @param hubName – The subdomain prefix to claim (e.g. "acme")
+     * @returns Promise resolving to the updated CollectionResponse (with hubName set)
+     * @throws ErrorResponse (400) on invalid/reserved name, (409) if already taken by another collection
+     */
+    function claimHub(collectionId: string, hubName: string): Promise<CollectionResponse>;
+    /**
+     * Register a custom domain for a collection and provision its managed
+     * certificate (admin only).
+     *
+     * @param collectionId – Identifier of the collection
+     * @param domain – The fully-qualified domain to register (e.g. "hub.acme.com")
+     * @param target – Which load balancer / certificate map to use. Defaults to
+     *   `"smartlinks"` (the id.smartlinks.app load balancer). Pass `"hub"` to
+     *   register a bring-your-own Hub domain.
+     * @returns Promise resolving when registration has been initiated
+     * @throws ErrorResponse if the request fails
+     */
+    function registerDomain(collectionId: string, domain: string, target?: DomainTarget): Promise<any>;
+    /**
+     * Get the managed-certificate status for a collection's custom domain (admin only).
+     * @param collectionId – Identifier of the collection
+     * @param target – Which domain to check: `"smartlinks"` (default, uses `redirectUrl`)
+     *   or `"hub"` (uses `hubCustomDomain`)
+     * @returns Promise resolving to the certificate details
+     * @throws ErrorResponse (404) if the relevant domain is not set
+     */
+    function getDomainStatus(collectionId: string, target?: DomainTarget): Promise<any>;
     /**
      * Retrieve a specific settings group for a collection.
      * Public reads return the public view of the settings group. If the stored payload contains

package/dist/api/collection.js

@@ -37,6 +37,100 @@ export var collection;
         return request(path);
     }
     collection.getShortId = getShortId;
+    /**
+     * Resolve the collection for the current Hub domain (public endpoint).
+     *
+     * The server derives the requesting domain from the request headers
+     * (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is
+     * passed — this is the call a Hub frontend makes on load to find out which
+     * collection it is serving, whether it's reached via `{brand}.mysmartlinks.app`
+     * or a bring-your-own custom domain (e.g. `hub.acme.com`).
+     *
+     * @returns Promise resolving to the CollectionResponse mapped to the domain
+     * @throws ErrorResponse (404) if no collection is mapped to the domain
+     */
+    async function getByHub() {
+        const path = `/public/collection/getByHub`;
+        return request(path);
+    }
+    collection.getByHub = getByHub;
+    /**
+     * Resolve the collection for an explicit Hub domain (public endpoint).
+     *
+     * Unlike {@link getByHub}, the domain is passed explicitly rather than derived
+     * from request headers — use this for raw/cross-origin calls where the Hub
+     * frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+     *
+     * @param domain – The Hub domain to resolve (custom domain or {brand}.mysmartlinks.app)
+     * @returns Promise resolving to the CollectionResponse mapped to the domain
+     * @throws ErrorResponse (404) if no collection is mapped to the domain
+     */
+    async function getByDomain(domain) {
+        const path = `/public/collection/by-domain/${encodeURIComponent(domain)}`;
+        return request(path);
+    }
+    collection.getByDomain = getByDomain;
+    /**
+     * Check whether a Hub subdomain name is available to claim (admin only).
+     * @param collectionId – Identifier of the collection making the request
+     * @param name – Proposed subdomain prefix (lowercase letters, numbers, hyphens; max 63 chars)
+     * @returns Promise resolving to { available, domain }
+     * @throws ErrorResponse (400) if the name fails validation or is reserved
+     */
+    async function checkHubAvailability(collectionId, name) {
+        const queryParams = new URLSearchParams({ name });
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/hub/available?${queryParams}`;
+        return request(path);
+    }
+    collection.checkHubAvailability = checkHubAvailability;
+    /**
+     * Claim or rename the Hub subdomain for a collection (admin only).
+     *
+     * Maps `{hubName}.mysmartlinks.app` to the collection. If the collection
+     * already had a different hub name, the previous subdomain is released
+     * automatically.
+     *
+     * @param collectionId – Identifier of the collection
+     * @param hubName – The subdomain prefix to claim (e.g. "acme")
+     * @returns Promise resolving to the updated CollectionResponse (with hubName set)
+     * @throws ErrorResponse (400) on invalid/reserved name, (409) if already taken by another collection
+     */
+    async function claimHub(collectionId, hubName) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/hub`;
+        return post(path, { hubName });
+    }
+    collection.claimHub = claimHub;
+    /**
+     * Register a custom domain for a collection and provision its managed
+     * certificate (admin only).
+     *
+     * @param collectionId – Identifier of the collection
+     * @param domain – The fully-qualified domain to register (e.g. "hub.acme.com")
+     * @param target – Which load balancer / certificate map to use. Defaults to
+     *   `"smartlinks"` (the id.smartlinks.app load balancer). Pass `"hub"` to
+     *   register a bring-your-own Hub domain.
+     * @returns Promise resolving when registration has been initiated
+     * @throws ErrorResponse if the request fails
+     */
+    async function registerDomain(collectionId, domain, target = "smartlinks") {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/domain`;
+        return post(path, { domain, target });
+    }
+    collection.registerDomain = registerDomain;
+    /**
+     * Get the managed-certificate status for a collection's custom domain (admin only).
+     * @param collectionId – Identifier of the collection
+     * @param target – Which domain to check: `"smartlinks"` (default, uses `redirectUrl`)
+     *   or `"hub"` (uses `hubCustomDomain`)
+     * @returns Promise resolving to the certificate details
+     * @throws ErrorResponse (404) if the relevant domain is not set
+     */
+    async function getDomainStatus(collectionId, target = "smartlinks") {
+        const queryParams = new URLSearchParams({ target });
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/domain?${queryParams}`;
+        return request(path);
+    }
+    collection.getDomainStatus = getDomainStatus;
     /**
      * Retrieve a specific settings group for a collection.
      * Public reads return the public view of the settings group. If the stored payload contains

package/dist/api/facets.d.ts

@@ -1,4 +1,4 @@
-import type { FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetQueryRequest, FacetQueryResponse, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams } from "../types/facets";
+import type { FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams } from "../types/facets";
 /**
  * Facet management and aggregation endpoints.
  *
@@ -18,9 +18,11 @@ export declare namespace facets {
     function updateValue(collectionId: string, facetKey: string, valueKey: string, data: FacetValueWriteInput): Promise<FacetValueResponse>;
     function removeValue(collectionId: string, facetKey: string, valueKey: string): Promise<void>;
     function query(collectionId: string, body: FacetQueryRequest): Promise<FacetQueryResponse>;
+    function namespaces(collectionId: string): Promise<FacetNamespaceListResponse>;
     function publicList(collectionId: string, params?: PublicFacetListParams): Promise<FacetListResponse>;
     function publicGet(collectionId: string, facetKey: string, params?: PublicFacetListParams): Promise<FacetDefinition>;
     function publicListValues(collectionId: string, facetKey: string): Promise<FacetValueListResponse>;
     function publicGetValue(collectionId: string, facetKey: string, valueKey: string): Promise<FacetValueResponse>;
     function publicQuery(collectionId: string, body: FacetQueryRequest): Promise<FacetQueryResponse>;
+    function publicNamespaces(collectionId: string): Promise<FacetNamespaceListResponse>;
 }

package/dist/api/facets.js

@@ -78,6 +78,11 @@ export var facets;
         return post(path, body);
     }
     facets.query = query;
+    async function namespaces(collectionId) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/facets/namespaces`;
+        return request(path);
+    }
+    facets.namespaces = namespaces;
     async function publicList(collectionId, params) {
         const path = `/public/collection/${encodeURIComponent(collectionId)}/facets${buildQueryString(params)}`;
         return request(path);
@@ -103,4 +108,9 @@ export var facets;
         return post(path, body);
     }
     facets.publicQuery = publicQuery;
+    async function publicNamespaces(collectionId) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/facets/namespaces`;
+        return request(path);
+    }
+    facets.publicNamespaces = publicNamespaces;
 })(facets || (facets = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.0  |  Generated: 2026-06-03T10:03:05.999Z
+Version: 1.15.2  |  Generated: 2026-07-05T07:39:20.416Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3606,6 +3606,8 @@ interface Collection {
   } // User roles mapping with user IDs as keys and role names as values
   groupTags?: string[] // Array of group tag names
   redirectUrl?: string // Whether the collection has a custom domain
+  hubName?: string
+  hubCustomDomain?: string
   shortId: string, // The shortId of this collection
   dark?: boolean // if dark mode is enabled for this collection
   primaryColor?: string
@@ -3618,6 +3620,14 @@ interface Collection {
 }
 ```
 
+**HubAvailabilityResponse** (interface)
+```typescript
+interface HubAvailabilityResponse {
+  available: boolean
+  domain: string
+}
+```
+
 **AppConfig** (interface)
 ```typescript
 interface AppConfig {
@@ -3657,6 +3667,8 @@ interface AppsConfigResponse {
 
 **CollectionUpdateRequest** = `Partial<Omit<Collection, 'id' | 'shortId'>>`
 
+**DomainTarget** = `"smartlinks" | "hub"`
+
 ### common
 
 **IdField** = `'userId' | 'contactId'`
@@ -5027,6 +5039,7 @@ interface FacetDefinition {
   key: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: "single" | "multi"
   kind?: "system" | "custom"
   hierarchical?: boolean
@@ -5075,6 +5088,7 @@ interface FacetDefinitionWriteInput {
   key?: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: "single" | "multi"
   kind?: "system" | "custom"
   hierarchical?: boolean
@@ -5132,6 +5146,7 @@ interface FacetQueryRequest {
   facetKeys?: string[]
   includeEmpty?: boolean
   includeDeleted?: boolean
+  namespace?: string | null
   query?: ProductQueryRequest["query"] & {
   facetEquals?: Record<string, JsonValue | JsonValue[]>
   }
@@ -5170,6 +5185,7 @@ interface FacetListParams {
   includeDeleted?: boolean
   kind?: "system" | "custom"
   reserved?: boolean
+  namespace?: string
 }
 ```
 
@@ -5177,6 +5193,14 @@ interface FacetListParams {
 ```typescript
 interface PublicFacetListParams {
   includeValues?: boolean
+  namespace?: string
+}
+```
+
+**FacetNamespaceListResponse** (interface)
+```typescript
+interface FacetNamespaceListResponse {
+  namespaces: string[]
 }
 ```
 
@@ -8604,6 +8628,24 @@ Retrieves all Collections.
 **getShortId**(shortId: string) → `Promise<CollectionResponse>`
 Retrieve a collection by its shortId (public endpoint).
 
+**getByHub**() → `Promise<CollectionResponse>`
+Resolve the collection for the current Hub domain (public endpoint). The server derives the requesting domain from the request headers (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is passed — this is the call a Hub frontend makes on load to find out which collection it is serving, whether it's reached via `{brand}.mysmartlinks.app` or a bring-your-own custom domain (e.g. `hub.acme.com`).
+
+**getByDomain**(domain: string) → `Promise<CollectionResponse>`
+Resolve the collection for an explicit Hub domain (public endpoint). Unlike {@link getByHub}, the domain is passed explicitly rather than derived from request headers — use this for raw/cross-origin calls where the Hub frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+
+**checkHubAvailability**(collectionId: string, name: string) → `Promise<HubAvailabilityResponse>`
+Check whether a Hub subdomain name is available to claim (admin only).
+
+**claimHub**(collectionId: string, hubName: string) → `Promise<CollectionResponse>`
+Claim or rename the Hub subdomain for a collection (admin only). Maps `{hubName}.mysmartlinks.app` to the collection. If the collection already had a different hub name, the previous subdomain is released automatically.
+
+**registerDomain**(collectionId: string, domain: string, target: DomainTarget = "smartlinks") → `Promise<any>`
+Register a custom domain for a collection and provision its managed certificate (admin only). `"smartlinks"` (the id.smartlinks.app load balancer). Pass `"hub"` to register a bring-your-own Hub domain.
+
+**getDomainStatus**(collectionId: string, target: DomainTarget = "smartlinks") → `Promise<any>`
+Get the managed-certificate status for a collection's custom domain (admin only). or `"hub"` (uses `hubCustomDomain`)
+
 **getSettings**(collectionId: string, settingGroup: string, admin?: boolean) → `Promise<any>`
 Retrieve a specific settings group for a collection. Public reads return the public view of the settings group. If the stored payload contains a top-level `admin` object, that block is omitted from public responses and included when `admin === true`.
 
@@ -8915,6 +8957,8 @@ Delete a crate for a collection (admin only). This performs a soft delete. ```ty
 **query**(collectionId: string,
     body: FacetQueryRequest) → `Promise<FacetQueryResponse>`
 
+**namespaces**(collectionId: string) → `Promise<FacetNamespaceListResponse>`
+
 **publicList**(collectionId: string,
     params?: PublicFacetListParams) → `Promise<FacetListResponse>`
 
@@ -8932,6 +8976,8 @@ Delete a crate for a collection (admin only). This performs a soft delete. ```ty
 **publicQuery**(collectionId: string,
     body: FacetQueryRequest) → `Promise<FacetQueryResponse>`
 
+**publicNamespaces**(collectionId: string) → `Promise<FacetNamespaceListResponse>`
+
 ### form
 
 **get**(collectionId: string, formId: string, admin?: boolean) → `Promise<any>`

package/dist/docs/PRODUCT_FACETS_SDK.md

@@ -42,6 +42,21 @@ includeValues?: boolean
 includeDeleted?: boolean
 kind?: 'system' | 'custom'
 reserved?: boolean
+namespace?: string
+```
+
+When `namespace` is provided, returns facets matching that namespace plus global facets (`namespace: null`). Omit the param to return all facets.
+
+### List namespaces
+
+```ts
+GET /api/v1/admin/collection/:collectionId/facets/namespaces
+```
+
+Returns all distinct namespaces in use for the collection (excludes globals).
+
+```ts
+{ namespaces: string[] }
 ```
 
 ### Create facet definition
@@ -50,6 +65,8 @@ reserved?: boolean
 POST /api/v1/admin/collection/:collectionId/facets
 ```
 
+Pass `namespace` in the body to scope the facet to a domain (e.g. `"dpp"`, `"nutrition"`). Omit it to create a global facet.
+
 ### Get facet definition
 
 ```ts
@@ -146,6 +163,8 @@ Supported query filters now:
 - `tags`
 - `facetEquals`
 
+Body also accepts `namespace` (optional) to scope aggregation to a namespace plus global facets.
+
 ## Public endpoints
 
 ### List facet definitions
@@ -158,6 +177,21 @@ Optional query params:
 
 ```ts
 includeValues?: boolean
+namespace?: string
+```
+
+When `namespace` is provided, returns facets matching that namespace plus global facets (`namespace: null`). Omit the param to return all facets.
+
+### List namespaces
+
+```ts
+GET /api/v1/public/collection/:collectionId/facets/namespaces
+```
+
+Returns all distinct namespaces in use for the collection (excludes globals).
+
+```ts
+{ namespaces: string[] }
 ```
 
 ### Get facet definition
@@ -215,6 +249,7 @@ export interface FacetDefinition {
   key: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality: 'single' | 'multi'
   kind: 'system' | 'custom'
   hierarchical: boolean
@@ -230,6 +265,7 @@ export interface FacetDefinitionWriteInput {
   key?: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: 'single' | 'multi'
   kind?: 'system' | 'custom'
   hierarchical?: boolean
@@ -305,6 +341,7 @@ export interface FacetQueryRequest {
   facetKeys?: string[]
   includeEmpty?: boolean
   includeDeleted?: boolean
+  namespace?: string | null
   query?: {
     search?: string
     status?: string[]
@@ -326,6 +363,10 @@ export interface FacetBucket {
   count: number
 }
 
+export interface FacetNamespaceListResponse {
+  namespaces: string[]
+}
+
 export interface FacetQueryResponse {
   items: Array<{
     facet: FacetDefinition
@@ -344,4 +385,5 @@ export interface FacetQueryResponse {
 - treat facet definitions and facet values as collection-scoped resources
 - use the facet API to manage definitions and values
 - use product read/write routes to assign facet data onto products
-- treat `label` and `category` as reserved system facets when present
+- treat `label` and `category` as reserved system facets when present
+- facets with `namespace: null` are global and appear in all contexts; namespaced facets belong to a specific domain (e.g. `"dpp"`, `"nutrition"`)

package/dist/http.js

@@ -91,7 +91,9 @@ const CACHE_TTL_RULES = [
     // Sub-resources that change frequently — short TTLs, listed first
     { pattern: /\/proof\/[^/]*(\?.*)?$/i, ttlMs: 30000 },
     { pattern: /\/attestation\/[^/]*(\?.*)?$/i, ttlMs: 2 * 60000 },
-    // Slow-changing top-level resources — long TTLs, matched only when path ends at the ID
+    // Slow-changing top-level resources — long TTLs, matched only when path ends at the ID.
+    // getByHub maps a stable Hub domain → collection and matches the /collection rule below,
+    // so it inherits the same 1h caching as a collection detail.
     { pattern: /\/products?\/[^/]*(\?.*)?$/i, ttlMs: 60 * 60000 },
     { pattern: /\/variant\/[^/]*(\?.*)?$/i, ttlMs: 60 * 60000 },
     { pattern: /\/collection\/[^/]*(\?.*)?$/i, ttlMs: 60 * 60000 }, // 1 hour

package/dist/index.d.ts

@@ -15,8 +15,8 @@ export type { BroadcastSendRequest } from "./types/broadcasts";
 export type { AppConfigOptions } from "./api/appConfiguration";
 export type { AdditionalGtin, ISODateString, JsonPrimitive, JsonValue, ProductCreateRequest, ProductClaimCreateInput, ProductClaimCreateRequestBody, ProductClaimLookupInput, ProductFacetMap, ProductFacetValue, ProductImageUrlInput, ProductKey, ProductQueryRequest, ProductQueryResponse, ProductUpdateRequest, Product, ProductWriteInput, PublicProduct, } from "./types/product";
 export type { TranslationLookupMode, TranslationContentType, TranslationQuality, TranslationItemStatus, TranslationContextValue, TranslationContext, TranslationLookupRequestBase, TranslationLookupSingleRequest, TranslationLookupBatchRequest, TranslationLookupRequest, TranslationLookupItem, TranslationLookupResponse, ResolvedTranslationItem, ResolvedTranslationResponse, TranslationHashOptions, TranslationResolveOptions, TranslationRecord, TranslationListParams, TranslationListResponse, TranslationUpdateRequest, } from "./types/translations";
-export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
-export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, } from "./types/collection";
+export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
+export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, DomainTarget, HubAvailabilityResponse, } from "./types/collection";
 export type { Proof, ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, } from "./types/proof";
 export type { QrShortCodeLookupResponse, } from "./types/qr";
 export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags";