@ptkl/sdk 1.3.2 → 1.4.0

package/dist/v0.10/api/system.d.ts

@@ -1,4 +1,41 @@
 import PlatformBaseClient from "./platformBaseClient";
+export type IDLAllResponse = {
+    components: Record<string, unknown>;
+    functions: Record<string, unknown>;
+};
+export type IDLValidateRequest = {
+    /** Compound ref, e.g. "component:ns::name", "pfn:fnName". Mutually exclusive with `idl`. */
+    ref?: string;
+    /** Inline IDL to validate against. Mutually exclusive with `ref`. */
+    idl?: Record<string, unknown>;
+    /** Field key to validate (required for component/extension refs, ignored for pfn). */
+    field?: string;
+    /** The value to validate. */
+    value: unknown;
+};
+export type IDLValidateResponse = {
+    valid: boolean;
+    errors?: Array<{
+        field?: string;
+        message: string;
+    }>;
+};
 export default class System extends PlatformBaseClient {
-    resourceResolver(ref: string, resourceName: string, format?: string): Promise<import("axios").AxiosResponse<any, any>>;
+    /**
+     * Returns all IDL definitions for the current project.
+     * Used by `ptkl generate-types` to emit typed `.d.ts` augmentations.
+     */
+    idl(): Promise<{
+        data: IDLAllResponse;
+    }>;
+    /**
+     * Validates a value against an IDL — either by ref or with an inline IDL object.
+     * Returns `{ data: { valid: true } }` on success or
+     * `{ data: { valid: false, errors: [...] } }` on validation failure.
+     * Throws on HTTP errors (4xx/5xx).
+     */
+    idlValidate(req: IDLValidateRequest): Promise<{
+        data: IDLValidateResponse;
+    }>;
+    resourceResolver(prn: string, format?: string): Promise<import("axios").AxiosResponse<any, any>>;
 }

package/dist/v0.10/index.cjs.js

@@ -19014,11 +19014,15 @@ class PlatformBaseClient extends BaseClient {
             token = (_c = __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_API_TOKEN) !== null && _c !== void 0 ? _c : token;
             project_uuid = __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_UUID;
             if (isBrowser) {
-                if (sessionStorage.getItem('protokol_context') == "forge") {
-                    headers['X-Project-Env'] = (_d = sessionStorage.getItem('forge_app_env')) !== null && _d !== void 0 ? _d : "dev";
+                if (sessionStorage.getItem('protokol_context') === 'forge') {
+                    headers['X-Project-Env'] = (_d = sessionStorage.getItem('forge_app_env')) !== null && _d !== void 0 ? _d : 'dev';
+                    // pick up forge actor token — overrides any other token source
+                    const forgeToken = sessionStorage.getItem('forge_actor_token');
+                    if (forgeToken)
+                        token = forgeToken;
                 }
                 else {
-                    headers['X-Project-Env'] = (_e = localStorage.getItem('current_env')) !== null && _e !== void 0 ? _e : "dev";
+                    headers['X-Project-Env'] = (_e = localStorage.getItem('current_env')) !== null && _e !== void 0 ? _e : 'dev';
                 }
             }
         }
@@ -19054,6 +19058,11 @@ class PlatformBaseClient extends BaseClient {
 }
 
 class Component extends PlatformBaseClient {
+    /**
+     * @param ref - Component ref (e.g. "ecommerce::order"). Passing a string
+     *   literal lets TypeScript infer the generic C and type find/create/function
+     *   results accordingly.
+     */
     constructor(ref = null) {
         super();
         this.ref = ref;
@@ -19080,6 +19089,7 @@ class Component extends PlatformBaseClient {
      * )
      **/
     async find(filters, opts) {
+        var _a;
         let payload = {
             context: filters,
             ref: this.ref,
@@ -19111,6 +19121,12 @@ class Component extends PlatformBaseClient {
             dateTo: ctx.dateTo,
             dateField: ctx.dateField,
         };
+        if (Object.keys(ctx.$adv || []).length > 0) {
+            params.$adv = [(_a = ctx.$adv) !== null && _a !== void 0 ? _a : {}];
+        }
+        if (ctx.$aggregate && ctx.$aggregate.length > 0) {
+            params.$aggregate = ctx.$aggregate;
+        }
         return await this.client.post(`/v4/system/component/${this.ref}/models`, {
             ...params,
             options: opts
@@ -19192,7 +19208,7 @@ class Component extends PlatformBaseClient {
     async updateMany(data, options) {
         return await this.client.patch(`/v4/system/component/${this.ref}/models/bulk`, {
             data,
-            options
+            options,
         });
     }
     /**
@@ -19597,16 +19613,6 @@ class Functions extends PlatformBaseClient {
     async update(uuid, update) {
         return await this.client.patch(`/v1/system/function/${uuid}`, update);
     }
-    /**
-     * Run platform function
-     *
-     * @param id - Function ID
-     * @param d - Object containing input data, query parameters, and headers
-     * @returns - Function result
-     *
-     * @example
-     * const result = await platform.function().run("myFunction", {input: { foo: "bar" }})
-     */
     async run(id, d) {
         const { data } = await this.client.post(`/v1/system/function/run/${id}`, d.input, {
             params: d.query,
@@ -20061,10 +20067,25 @@ class Sandbox extends PlatformBaseClient {
 }
 
 class System extends PlatformBaseClient {
-    async resourceResolver(ref, resourceName, format) {
+    /**
+     * Returns all IDL definitions for the current project.
+     * Used by `ptkl generate-types` to emit typed `.d.ts` augmentations.
+     */
+    async idl() {
+        return await this.client.get('/v1/system/idl');
+    }
+    /**
+     * Validates a value against an IDL — either by ref or with an inline IDL object.
+     * Returns `{ data: { valid: true } }` on success or
+     * `{ data: { valid: false, errors: [...] } }` on validation failure.
+     * Throws on HTTP errors (4xx/5xx).
+     */
+    async idlValidate(req) {
+        return await this.client.post('/v1/system/idl/validate', req);
+    }
+    async resourceResolver(prn, format) {
         return await this.client.post("/v3/system/resource-resolver", {
-            type: resourceName,
-            ref,
+            prn,
             format,
         });
     }
@@ -20366,11 +20387,15 @@ class IntegrationsBaseClient extends BaseClient {
             env = env !== null && env !== void 0 ? env : __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_ENV;
             token = token !== null && token !== void 0 ? token : __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_API_TOKEN;
             if (isBrowser) {
-                if (sessionStorage.getItem('protokol_context') == "forge") {
-                    headers['X-Project-Env'] = (_b = sessionStorage.getItem('forge_app_env')) !== null && _b !== void 0 ? _b : "dev";
+                if (sessionStorage.getItem('protokol_context') === 'forge') {
+                    headers['X-Project-Env'] = (_b = sessionStorage.getItem('forge_app_env')) !== null && _b !== void 0 ? _b : 'dev';
+                    // pick up forge actor token — overrides any other token source
+                    const forgeToken = sessionStorage.getItem('forge_actor_token');
+                    if (forgeToken)
+                        token = forgeToken;
                 }
                 else {
-                    headers['X-Project-Env'] = (_c = localStorage.getItem('current_env')) !== null && _c !== void 0 ? _c : "dev";
+                    headers['X-Project-Env'] = (_c = localStorage.getItem('current_env')) !== null && _c !== void 0 ? _c : 'dev';
                 }
             }
         }
@@ -22166,6 +22191,57 @@ class NBS extends IntegrationsBaseClient {
     }
 }
 
+class Ecommerce extends IntegrationsBaseClient {
+    /**
+     * Get the ecommerce integration user for the current project.
+     */
+    async get() {
+        return await this.client.get(`/v1/ecomm/user`);
+    }
+    /**
+     * Update ecommerce integration settings (onboarding or partial update).
+     */
+    async update(req) {
+        return await this.client.patch(`/v1/ecomm/user`, req);
+    }
+    /**
+     * Check whether a base domain subdomain is available.
+     */
+    async checkBaseDomain(domain) {
+        return await this.client.post(`/v1/ecomm/base-domain/check`, { domain });
+    }
+    /**
+     * Add a custom domain (returns a verification token for DNS validation).
+     */
+    async addCustomDomain(domain) {
+        return await this.client.post(`/v1/ecomm/domains`, { domain });
+    }
+    /**
+     * Validate a custom domain with its verification token.
+     */
+    async validateCustomDomain(domain, token) {
+        return await this.client.post(`/v1/ecomm/domains/validate`, { domain, token });
+    }
+    /**
+     * Remove a custom domain.
+     */
+    async removeCustomDomain(domain) {
+        return await this.client.delete(`/v1/ecomm/domains`, { data: { domain } });
+    }
+    /**
+     * List pending (unvalidated) custom domains.
+     */
+    async getPendingDomains() {
+        return await this.client.get(`/v1/ecomm/domains/pending`);
+    }
+    /**
+     * List validated custom domains.
+     */
+    async getValidatedDomains() {
+        return await this.client.get(`/v1/ecomm/domains/validated`);
+    }
+}
+
 class Integrations extends IntegrationsBaseClient {
     constructor(options) {
         super(options);
@@ -22176,6 +22252,7 @@ class Integrations extends IntegrationsBaseClient {
             'nbs': new NBS().setClient(this.client),
             'protokol-payments': new Payments().setClient(this.client),
             'protokol-minimax': new Minimax().setClient(this.client),
+            'protokol-ecommerce': new Ecommerce().setClient(this.client),
         };
     }
     getDMS() {
@@ -22199,6 +22276,9 @@ class Integrations extends IntegrationsBaseClient {
     getSerbiaMinFin() {
         return this.getInterfaceOf('serbia-minfin');
     }
+    getEcommerce() {
+        return this.getInterfaceOf('protokol-ecommerce');
+    }
     async isInstalled(id) {
         const { data } = await this.client.get("/v1/integrations");
         return data.find((i) => i.id == id) !== undefined;
@@ -22244,6 +22324,7 @@ exports.Component = Component;
 exports.ComponentUtils = ComponentUtils;
 exports.Config = Config;
 exports.DMS = DMS;
+exports.Ecommerce = Ecommerce;
 exports.Forge = Forge;
 exports.Functions = Functions;
 exports.Integration = Integrations;

package/dist/v0.10/index.esm.js

@@ -47,11 +47,15 @@ class PlatformBaseClient extends BaseClient {
             token = (_c = __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_API_TOKEN) !== null && _c !== void 0 ? _c : token;
             project_uuid = __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_UUID;
             if (isBrowser) {
-                if (sessionStorage.getItem('protokol_context') == "forge") {
-                    headers['X-Project-Env'] = (_d = sessionStorage.getItem('forge_app_env')) !== null && _d !== void 0 ? _d : "dev";
+                if (sessionStorage.getItem('protokol_context') === 'forge') {
+                    headers['X-Project-Env'] = (_d = sessionStorage.getItem('forge_app_env')) !== null && _d !== void 0 ? _d : 'dev';
+                    // pick up forge actor token — overrides any other token source
+                    const forgeToken = sessionStorage.getItem('forge_actor_token');
+                    if (forgeToken)
+                        token = forgeToken;
                 }
                 else {
-                    headers['X-Project-Env'] = (_e = localStorage.getItem('current_env')) !== null && _e !== void 0 ? _e : "dev";
+                    headers['X-Project-Env'] = (_e = localStorage.getItem('current_env')) !== null && _e !== void 0 ? _e : 'dev';
                 }
             }
         }
@@ -87,6 +91,11 @@ class PlatformBaseClient extends BaseClient {
 }
 
 class Component extends PlatformBaseClient {
+    /**
+     * @param ref - Component ref (e.g. "ecommerce::order"). Passing a string
+     *   literal lets TypeScript infer the generic C and type find/create/function
+     *   results accordingly.
+     */
     constructor(ref = null) {
         super();
         this.ref = ref;
@@ -113,6 +122,7 @@ class Component extends PlatformBaseClient {
      * )
      **/
     async find(filters, opts) {
+        var _a;
         let payload = {
             context: filters,
             ref: this.ref,
@@ -144,6 +154,12 @@ class Component extends PlatformBaseClient {
             dateTo: ctx.dateTo,
             dateField: ctx.dateField,
         };
+        if (Object.keys(ctx.$adv || []).length > 0) {
+            params.$adv = [(_a = ctx.$adv) !== null && _a !== void 0 ? _a : {}];
+        }
+        if (ctx.$aggregate && ctx.$aggregate.length > 0) {
+            params.$aggregate = ctx.$aggregate;
+        }
         return await this.client.post(`/v4/system/component/${this.ref}/models`, {
             ...params,
             options: opts
@@ -225,7 +241,7 @@ class Component extends PlatformBaseClient {
     async updateMany(data, options) {
         return await this.client.patch(`/v4/system/component/${this.ref}/models/bulk`, {
             data,
-            options
+            options,
         });
     }
     /**
@@ -630,16 +646,6 @@ class Functions extends PlatformBaseClient {
     async update(uuid, update) {
         return await this.client.patch(`/v1/system/function/${uuid}`, update);
     }
-    /**
-     * Run platform function
-     *
-     * @param id - Function ID
-     * @param d - Object containing input data, query parameters, and headers
-     * @returns - Function result
-     *
-     * @example
-     * const result = await platform.function().run("myFunction", {input: { foo: "bar" }})
-     */
     async run(id, d) {
         const { data } = await this.client.post(`/v1/system/function/run/${id}`, d.input, {
             params: d.query,
@@ -1094,10 +1100,25 @@ class Sandbox extends PlatformBaseClient {
 }
 
 class System extends PlatformBaseClient {
-    async resourceResolver(ref, resourceName, format) {
+    /**
+     * Returns all IDL definitions for the current project.
+     * Used by `ptkl generate-types` to emit typed `.d.ts` augmentations.
+     */
+    async idl() {
+        return await this.client.get('/v1/system/idl');
+    }
+    /**
+     * Validates a value against an IDL — either by ref or with an inline IDL object.
+     * Returns `{ data: { valid: true } }` on success or
+     * `{ data: { valid: false, errors: [...] } }` on validation failure.
+     * Throws on HTTP errors (4xx/5xx).
+     */
+    async idlValidate(req) {
+        return await this.client.post('/v1/system/idl/validate', req);
+    }
+    async resourceResolver(prn, format) {
         return await this.client.post("/v3/system/resource-resolver", {
-            type: resourceName,
-            ref,
+            prn,
             format,
         });
     }
@@ -1399,11 +1420,15 @@ class IntegrationsBaseClient extends BaseClient {
             env = env !== null && env !== void 0 ? env : __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_ENV;
             token = token !== null && token !== void 0 ? token : __global_env__ === null || __global_env__ === void 0 ? void 0 : __global_env__.PROJECT_API_TOKEN;
             if (isBrowser) {
-                if (sessionStorage.getItem('protokol_context') == "forge") {
-                    headers['X-Project-Env'] = (_b = sessionStorage.getItem('forge_app_env')) !== null && _b !== void 0 ? _b : "dev";
+                if (sessionStorage.getItem('protokol_context') === 'forge') {
+                    headers['X-Project-Env'] = (_b = sessionStorage.getItem('forge_app_env')) !== null && _b !== void 0 ? _b : 'dev';
+                    // pick up forge actor token — overrides any other token source
+                    const forgeToken = sessionStorage.getItem('forge_actor_token');
+                    if (forgeToken)
+                        token = forgeToken;
                 }
                 else {
-                    headers['X-Project-Env'] = (_c = localStorage.getItem('current_env')) !== null && _c !== void 0 ? _c : "dev";
+                    headers['X-Project-Env'] = (_c = localStorage.getItem('current_env')) !== null && _c !== void 0 ? _c : 'dev';
                 }
             }
         }
@@ -3199,6 +3224,57 @@ class NBS extends IntegrationsBaseClient {
     }
 }
 
+class Ecommerce extends IntegrationsBaseClient {
+    /**
+     * Get the ecommerce integration user for the current project.
+     */
+    async get() {
+        return await this.client.get(`/v1/ecomm/user`);
+    }
+    /**
+     * Update ecommerce integration settings (onboarding or partial update).
+     */
+    async update(req) {
+        return await this.client.patch(`/v1/ecomm/user`, req);
+    }
+    /**
+     * Check whether a base domain subdomain is available.
+     */
+    async checkBaseDomain(domain) {
+        return await this.client.post(`/v1/ecomm/base-domain/check`, { domain });
+    }
+    /**
+     * Add a custom domain (returns a verification token for DNS validation).
+     */
+    async addCustomDomain(domain) {
+        return await this.client.post(`/v1/ecomm/domains`, { domain });
+    }
+    /**
+     * Validate a custom domain with its verification token.
+     */
+    async validateCustomDomain(domain, token) {
+        return await this.client.post(`/v1/ecomm/domains/validate`, { domain, token });
+    }
+    /**
+     * Remove a custom domain.
+     */
+    async removeCustomDomain(domain) {
+        return await this.client.delete(`/v1/ecomm/domains`, { data: { domain } });
+    }
+    /**
+     * List pending (unvalidated) custom domains.
+     */
+    async getPendingDomains() {
+        return await this.client.get(`/v1/ecomm/domains/pending`);
+    }
+    /**
+     * List validated custom domains.
+     */
+    async getValidatedDomains() {
+        return await this.client.get(`/v1/ecomm/domains/validated`);
+    }
+}
+
 class Integrations extends IntegrationsBaseClient {
     constructor(options) {
         super(options);
@@ -3209,6 +3285,7 @@ class Integrations extends IntegrationsBaseClient {
             'nbs': new NBS().setClient(this.client),
             'protokol-payments': new Payments().setClient(this.client),
             'protokol-minimax': new Minimax().setClient(this.client),
+            'protokol-ecommerce': new Ecommerce().setClient(this.client),
         };
     }
     getDMS() {
@@ -3232,6 +3309,9 @@ class Integrations extends IntegrationsBaseClient {
     getSerbiaMinFin() {
         return this.getInterfaceOf('serbia-minfin');
     }
+    getEcommerce() {
+        return this.getInterfaceOf('protokol-ecommerce');
+    }
     async isInstalled(id) {
         const { data } = await this.client.get("/v1/integrations");
         return data.find((i) => i.id == id) !== undefined;
@@ -3271,4 +3351,4 @@ class Invoicing extends PlatformBaseClient {
     }
 }
 
-export { APIUser, Apps, Component, ComponentUtils, Config, DMS, Forge, Functions, Integrations as Integration, Integrations, Invoicing, Mail, NBS, Payments, Platform, Project, Ratchet, Sandbox, MinFin as SerbiaMinFin, System, Thunder, Users, VPFR, Workflow };
+export { APIUser, Apps, Component, ComponentUtils, Config, DMS, Ecommerce, Forge, Functions, Integrations as Integration, Integrations, Invoicing, Mail, NBS, Payments, Platform, Project, Ratchet, Sandbox, MinFin as SerbiaMinFin, System, Thunder, Users, VPFR, Workflow };

package/dist/v0.10/types/component.d.ts

@@ -65,16 +65,17 @@ type Model = {
     [key: string]: any;
 };
 type UpdateOptions = {
-    forceUpdateProtectedFields: boolean;
+    force_update_protected_fields: boolean;
 };
 type UpdateManyOptions = UpdateOptions & {
-    rollbackOnError: boolean;
+    rollback_on_error: boolean;
 };
 type CreateManyOptions = {
-    rollbackOnError: boolean;
+    rollback_on_error: boolean;
 };
 type ModifyOptions = {
     upsert: boolean;
+    force_update_protected_fields?: boolean;
 };
 /**
  * MongoDB update operators that can be included inline in the `data` payload.

package/dist/v0.10/types/functions.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ComponentModels maps component/extension refs to their IDL field shapes.
+ * Keys follow the pattern "namespace::name" or "namespace::name/extensionName".
+ * Populated at runtime by Monaco via declaration merging.
+ *
+ * @example
+ * type OrderFields = ComponentModels["ecommerce::order"]
+ */
+export interface ComponentModels {
+}
+/**
+ * ComponentFunctions maps component/extension refs to their function signatures.
+ * Each key is a component ref ("namespace::name") and the value maps function
+ * names to their IDL-derived input/output shapes.
+ *
+ * @example
+ * type TestFn = ComponentFunctions["ecommerce::order"]["test"]
+ * // → { input: { discount?: number; items: number[] }; output: { item_count?: number; total?: number } }
+ */
+export interface ComponentFunctions {
+}
+/**
+ * PlatformFunctions is an open interface that serves as a registry of platform
+ * function signatures. It is empty by default and can be extended:
+ *
+ * **At build time** — run `ptkl generate-types` to fetch your project's
+ * functions and emit a `.d.ts` file with a module augmentation block:
+ * ```ts
+ * declare module "@ptkl/sdk" {
+ *   interface PlatformFunctions {
+ *     "send_email": { input: { body: string; to: string }; output: { status: boolean } }
+ *   }
+ * }
+ * ```
+ */
+export interface PlatformFunctions {
+}
+/**
+ * Access a single platform function's signature type by name.
+ *
+ * @example
+ * type EmailSig = PlatformFunction<"send_email">
+ * // → { input: { body: string; to: string }; output: { status: boolean } }
+ */
+export type PlatformFunction<K extends keyof PlatformFunctions> = PlatformFunctions[K];
+/** Inferred input type for a registered function, falling back to a generic record. */
+export type FunctionInput<K extends keyof PlatformFunctions> = PlatformFunctions[K] extends {
+    input: infer I;
+} ? I : Record<string, any>;
+/** Inferred output type for a registered function, falling back to any. */
+export type FunctionOutput<K extends keyof PlatformFunctions> = PlatformFunctions[K] extends {
+    output: infer O;
+} ? O : any;
+/** Parameters shape for a typed function call. */
+export type FunctionCallParams<K extends keyof PlatformFunctions> = {
+    input: FunctionInput<K>;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+};
+/** Resolved field shape for a known component ref. */
+export type ComponentModel<C extends keyof ComponentModels> = ComponentModels[C];
+/**
+ * Inferred input type for a component function.
+ *
+ * @example
+ * type TestInput = ComponentFunctionInput<"ecommerce::order", "test">
+ * // → { discount?: number; items: number[] }
+ */
+export type ComponentFunctionInput<C extends keyof ComponentFunctions, F extends keyof ComponentFunctions[C]> = ComponentFunctions[C][F] extends {
+    input: infer I;
+} ? I : Record<string, any>;
+/**
+ * Inferred output type for a component function.
+ *
+ * @example
+ * type TestOutput = ComponentFunctionOutput<"ecommerce::order", "test">
+ * // → { item_count?: number; total?: number }
+ */
+export type ComponentFunctionOutput<C extends keyof ComponentFunctions, F extends keyof ComponentFunctions[C]> = ComponentFunctions[C][F] extends {
+    output: infer O;
+} ? O : any;