@ptkl/sdk 1.13.0 → 1.14.0

package/dist/index.0.10.js

@@ -1293,6 +1293,59 @@ var ProtokolSDK010 = (function (exports, axios) {
         }
     }
 
+    /**
+     * Resolve the current app's UUID from the ambient platform context.
+     * The platform injects it per-installation: FORGE_APP_UUID in __ENV_VARIABLES__
+     * for public views, and forge_app_uuid in sessionStorage for platform views.
+     * Returns null outside the browser (e.g. Node/CLI), where the caller must pass
+     * an explicit appUuid.
+     */
+    function resolveCurrentAppUuid() {
+        var _a;
+        if (!isBrowser)
+            return null;
+        // @ts-ignore
+        const fromEnv = (_a = window.__ENV_VARIABLES__) === null || _a === void 0 ? void 0 : _a.FORGE_APP_UUID;
+        if (fromEnv)
+            return fromEnv;
+        try {
+            return sessionStorage.getItem("forge_app_uuid");
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Resolve a service target into { ref, serviceName }.
+     *
+     * Two forms, cleanly split:
+     *  - a bare service name (no "prn:" prefix) → the CURRENT app's service (the ref
+     *    is the current app's uuid, resolved from the platform context); or
+     *  - a service PRN `prn:forge:{ref}:service/{serviceName}` → ANOTHER app's service
+     *    (canonical PRN grammar: kind + name in the path, url-encoded).
+     *
+     * A PRN's `ref` may be an app **name** OR a uuid. Names aren't unique within a
+     * project (a marketplace install and a custom app can share one), so the runtime
+     * resolves a name deterministically **marketplace → custom**. Pass the uuid when
+     * you need a *specific* app.
+     */
+    function parseServiceTarget(target) {
+        if (!target.startsWith("prn:")) {
+            // bare service name → the current app
+            return { ref: resolveCurrentAppUuid(), serviceName: target };
+        }
+        // PRN → another app. Path form: prn:forge:{ref}:service/{serviceName}
+        // (the PRN path segment is "service/{name}", with the name url-encoded).
+        const [, type, ref, ...rest] = target.split(":");
+        const path = rest.join(":"); // the PRN path, e.g. "service/{name}"
+        const [kind, ...nameParts] = path.split("/");
+        const serviceName = decodeURIComponent(nameParts.join("/"));
+        if (type !== "forge" || kind !== "service" || !ref || !serviceName) {
+            throw new Error(`runService: invalid service PRN "${target}" ` +
+                `(expected prn:forge:{ref}:service/{serviceName}, where ref is an app name or uuid)`);
+        }
+        return { ref, serviceName };
+    }
     class Forge extends PlatformBaseClient {
         // --- Management (appservice) ---
         async bundleUpload(buffer) {
@@ -1330,17 +1383,49 @@ var ProtokolSDK010 = (function (exports, axios) {
             return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, current);
         }
         // --- Service execution (forge-runtime) ---
-        async callService(appUuid, serviceName, options) {
-            var _a, _b, _c;
+        /**
+         * Run a Forge service: `runService(target, body?, { query?, headers? })`.
+         * Mirrors `axios.post(url, data, config)` — the 2nd arg is the request payload.
+         *
+         * `target` is either:
+         *  - a bare service name — runs that service on the CURRENT app; or
+         *  - a service PRN `prn:forge:{ref}:service/{name}` — runs it on ANOTHER app,
+         *    where `ref` is the app's **name** or uuid. A name is resolved by the
+         *    runtime deterministically (marketplace → custom); use the uuid to pin a
+         *    specific app. This is the addressing to use where there's no ambient
+         *    "current app" — e.g. a workflow, which has no per-install uuid to hardcode.
+         *
+         * `body` is sent as the POST body; `options.query` / `options.headers` are optional.
+         *
+         * The current app's uuid (bare-name form) is resolved automatically from the
+         * platform context (FORGE_APP_UUID for public views, forge_app_uuid in
+         * sessionStorage for platform views), so app code never needs its own uuid.
+         *
+         * Resolving the app does NOT grant access. Execution is still authorized against
+         * the caller's permissions — for a `platform`-access service the caller must hold
+         * `execute forge::service::{appUuid}::{name}`; `public`-access services require none.
+         */
+        async runService(target, body, options) {
+            var _a;
+            const { ref, serviceName } = parseServiceTarget(target);
             const queryString = (options === null || options === void 0 ? void 0 : options.query)
                 ? '?' + new URLSearchParams(options.query).toString()
                 : '';
             // @ts-ignore
             const devServiceUrl = isBrowser && ((_a = window.__ENV_VARIABLES__) === null || _a === void 0 ? void 0 : _a.FORGE_DEV_SERVICE_URL);
             if (devServiceUrl) {
-                return axios.post(`${devServiceUrl}/${serviceName}${queryString}`, (_b = options === null || options === void 0 ? void 0 : options.body) !== null && _b !== void 0 ? _b : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+                // The dev service server routes by name; the ref is ignored.
+                return axios.post(`${devServiceUrl}/${serviceName}${queryString}`, body !== null && body !== void 0 ? body : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+            }
+            if (!ref) {
+                throw new Error("runService: could not resolve the current app from the platform context. " +
+                    "Use a service PRN with an explicit ref: prn:forge:{name|uuid}:service/{serviceName}.");
             }
-            return await this.client.post(`/luma/forge-runtime/api/services/${appUuid}/${serviceName}${queryString}`, (_c = options === null || options === void 0 ? void 0 : options.body) !== null && _c !== void 0 ? _c : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+            // Service execution is owned by the forge runtime (forge-runtime gateway ->
+            // platform-forge), which resolves the ref (name → uuid, marketplace → custom)
+            // and executes the service, enforcing `execute forge::service::{uuid}::{name}`
+            // for platform-access services before running.
+            return await this.client.post(`/luma/forge-runtime/api/services/${ref}/${serviceName}${queryString}`, body !== null && body !== void 0 ? body : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
         }
     }
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptkl/sdk",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",

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

@@ -8,8 +8,29 @@ export default class Forge extends PlatformBaseClient {
     getVariables(ref: string): Promise<any>;
     updateVariables(ref: string, variables: Record<string, any>): Promise<any>;
     addVariable(ref: string, key: string, value: any): Promise<any>;
-    callService(appUuid: string, serviceName: string, options?: {
-        body?: any;
+    /**
+     * Run a Forge service: `runService(target, body?, { query?, headers? })`.
+     * Mirrors `axios.post(url, data, config)` — the 2nd arg is the request payload.
+     *
+     * `target` is either:
+     *  - a bare service name — runs that service on the CURRENT app; or
+     *  - a service PRN `prn:forge:{ref}:service/{name}` — runs it on ANOTHER app,
+     *    where `ref` is the app's **name** or uuid. A name is resolved by the
+     *    runtime deterministically (marketplace → custom); use the uuid to pin a
+     *    specific app. This is the addressing to use where there's no ambient
+     *    "current app" — e.g. a workflow, which has no per-install uuid to hardcode.
+     *
+     * `body` is sent as the POST body; `options.query` / `options.headers` are optional.
+     *
+     * The current app's uuid (bare-name form) is resolved automatically from the
+     * platform context (FORGE_APP_UUID for public views, forge_app_uuid in
+     * sessionStorage for platform views), so app code never needs its own uuid.
+     *
+     * Resolving the app does NOT grant access. Execution is still authorized against
+     * the caller's permissions — for a `platform`-access service the caller must hold
+     * `execute forge::service::{appUuid}::{name}`; `public`-access services require none.
+     */
+    runService(target: string, body?: any, options?: {
         query?: Record<string, string>;
         headers?: Record<string, string>;
     }): Promise<any>;

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

@@ -20259,6 +20259,59 @@ class Workflow extends PlatformBaseClient {
     }
 }
 
+/**
+ * Resolve the current app's UUID from the ambient platform context.
+ * The platform injects it per-installation: FORGE_APP_UUID in __ENV_VARIABLES__
+ * for public views, and forge_app_uuid in sessionStorage for platform views.
+ * Returns null outside the browser (e.g. Node/CLI), where the caller must pass
+ * an explicit appUuid.
+ */
+function resolveCurrentAppUuid() {
+    var _a;
+    if (!isBrowser)
+        return null;
+    // @ts-ignore
+    const fromEnv = (_a = window.__ENV_VARIABLES__) === null || _a === void 0 ? void 0 : _a.FORGE_APP_UUID;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        return sessionStorage.getItem("forge_app_uuid");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a service target into { ref, serviceName }.
+ *
+ * Two forms, cleanly split:
+ *  - a bare service name (no "prn:" prefix) → the CURRENT app's service (the ref
+ *    is the current app's uuid, resolved from the platform context); or
+ *  - a service PRN `prn:forge:{ref}:service/{serviceName}` → ANOTHER app's service
+ *    (canonical PRN grammar: kind + name in the path, url-encoded).
+ *
+ * A PRN's `ref` may be an app **name** OR a uuid. Names aren't unique within a
+ * project (a marketplace install and a custom app can share one), so the runtime
+ * resolves a name deterministically **marketplace → custom**. Pass the uuid when
+ * you need a *specific* app.
+ */
+function parseServiceTarget(target) {
+    if (!target.startsWith("prn:")) {
+        // bare service name → the current app
+        return { ref: resolveCurrentAppUuid(), serviceName: target };
+    }
+    // PRN → another app. Path form: prn:forge:{ref}:service/{serviceName}
+    // (the PRN path segment is "service/{name}", with the name url-encoded).
+    const [, type, ref, ...rest] = target.split(":");
+    const path = rest.join(":"); // the PRN path, e.g. "service/{name}"
+    const [kind, ...nameParts] = path.split("/");
+    const serviceName = decodeURIComponent(nameParts.join("/"));
+    if (type !== "forge" || kind !== "service" || !ref || !serviceName) {
+        throw new Error(`runService: invalid service PRN "${target}" ` +
+            `(expected prn:forge:{ref}:service/{serviceName}, where ref is an app name or uuid)`);
+    }
+    return { ref, serviceName };
+}
 class Forge extends PlatformBaseClient {
     // --- Management (appservice) ---
     async bundleUpload(buffer) {
@@ -20296,17 +20349,49 @@ class Forge extends PlatformBaseClient {
         return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, current);
     }
     // --- Service execution (forge-runtime) ---
-    async callService(appUuid, serviceName, options) {
-        var _a, _b, _c;
+    /**
+     * Run a Forge service: `runService(target, body?, { query?, headers? })`.
+     * Mirrors `axios.post(url, data, config)` — the 2nd arg is the request payload.
+     *
+     * `target` is either:
+     *  - a bare service name — runs that service on the CURRENT app; or
+     *  - a service PRN `prn:forge:{ref}:service/{name}` — runs it on ANOTHER app,
+     *    where `ref` is the app's **name** or uuid. A name is resolved by the
+     *    runtime deterministically (marketplace → custom); use the uuid to pin a
+     *    specific app. This is the addressing to use where there's no ambient
+     *    "current app" — e.g. a workflow, which has no per-install uuid to hardcode.
+     *
+     * `body` is sent as the POST body; `options.query` / `options.headers` are optional.
+     *
+     * The current app's uuid (bare-name form) is resolved automatically from the
+     * platform context (FORGE_APP_UUID for public views, forge_app_uuid in
+     * sessionStorage for platform views), so app code never needs its own uuid.
+     *
+     * Resolving the app does NOT grant access. Execution is still authorized against
+     * the caller's permissions — for a `platform`-access service the caller must hold
+     * `execute forge::service::{appUuid}::{name}`; `public`-access services require none.
+     */
+    async runService(target, body, options) {
+        var _a;
+        const { ref, serviceName } = parseServiceTarget(target);
         const queryString = (options === null || options === void 0 ? void 0 : options.query)
             ? '?' + new URLSearchParams(options.query).toString()
             : '';
         // @ts-ignore
         const devServiceUrl = isBrowser && ((_a = window.__ENV_VARIABLES__) === null || _a === void 0 ? void 0 : _a.FORGE_DEV_SERVICE_URL);
         if (devServiceUrl) {
-            return axios.post(`${devServiceUrl}/${serviceName}${queryString}`, (_b = options === null || options === void 0 ? void 0 : options.body) !== null && _b !== void 0 ? _b : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+            // The dev service server routes by name; the ref is ignored.
+            return axios.post(`${devServiceUrl}/${serviceName}${queryString}`, body !== null && body !== void 0 ? body : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+        }
+        if (!ref) {
+            throw new Error("runService: could not resolve the current app from the platform context. " +
+                "Use a service PRN with an explicit ref: prn:forge:{name|uuid}:service/{serviceName}.");
         }
-        return await this.client.post(`/luma/forge-runtime/api/services/${appUuid}/${serviceName}${queryString}`, (_c = options === null || options === void 0 ? void 0 : options.body) !== null && _c !== void 0 ? _c : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+        // Service execution is owned by the forge runtime (forge-runtime gateway ->
+        // platform-forge), which resolves the ref (name → uuid, marketplace → custom)
+        // and executes the service, enforcing `execute forge::service::{uuid}::{name}`
+        // for platform-access services before running.
+        return await this.client.post(`/luma/forge-runtime/api/services/${ref}/${serviceName}${queryString}`, body !== null && body !== void 0 ? body : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
     }
 }
 

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

@@ -1292,6 +1292,59 @@ class Workflow extends PlatformBaseClient {
     }
 }
 
+/**
+ * Resolve the current app's UUID from the ambient platform context.
+ * The platform injects it per-installation: FORGE_APP_UUID in __ENV_VARIABLES__
+ * for public views, and forge_app_uuid in sessionStorage for platform views.
+ * Returns null outside the browser (e.g. Node/CLI), where the caller must pass
+ * an explicit appUuid.
+ */
+function resolveCurrentAppUuid() {
+    var _a;
+    if (!isBrowser)
+        return null;
+    // @ts-ignore
+    const fromEnv = (_a = window.__ENV_VARIABLES__) === null || _a === void 0 ? void 0 : _a.FORGE_APP_UUID;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        return sessionStorage.getItem("forge_app_uuid");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a service target into { ref, serviceName }.
+ *
+ * Two forms, cleanly split:
+ *  - a bare service name (no "prn:" prefix) → the CURRENT app's service (the ref
+ *    is the current app's uuid, resolved from the platform context); or
+ *  - a service PRN `prn:forge:{ref}:service/{serviceName}` → ANOTHER app's service
+ *    (canonical PRN grammar: kind + name in the path, url-encoded).
+ *
+ * A PRN's `ref` may be an app **name** OR a uuid. Names aren't unique within a
+ * project (a marketplace install and a custom app can share one), so the runtime
+ * resolves a name deterministically **marketplace → custom**. Pass the uuid when
+ * you need a *specific* app.
+ */
+function parseServiceTarget(target) {
+    if (!target.startsWith("prn:")) {
+        // bare service name → the current app
+        return { ref: resolveCurrentAppUuid(), serviceName: target };
+    }
+    // PRN → another app. Path form: prn:forge:{ref}:service/{serviceName}
+    // (the PRN path segment is "service/{name}", with the name url-encoded).
+    const [, type, ref, ...rest] = target.split(":");
+    const path = rest.join(":"); // the PRN path, e.g. "service/{name}"
+    const [kind, ...nameParts] = path.split("/");
+    const serviceName = decodeURIComponent(nameParts.join("/"));
+    if (type !== "forge" || kind !== "service" || !ref || !serviceName) {
+        throw new Error(`runService: invalid service PRN "${target}" ` +
+            `(expected prn:forge:{ref}:service/{serviceName}, where ref is an app name or uuid)`);
+    }
+    return { ref, serviceName };
+}
 class Forge extends PlatformBaseClient {
     // --- Management (appservice) ---
     async bundleUpload(buffer) {
@@ -1329,17 +1382,49 @@ class Forge extends PlatformBaseClient {
         return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, current);
     }
     // --- Service execution (forge-runtime) ---
-    async callService(appUuid, serviceName, options) {
-        var _a, _b, _c;
+    /**
+     * Run a Forge service: `runService(target, body?, { query?, headers? })`.
+     * Mirrors `axios.post(url, data, config)` — the 2nd arg is the request payload.
+     *
+     * `target` is either:
+     *  - a bare service name — runs that service on the CURRENT app; or
+     *  - a service PRN `prn:forge:{ref}:service/{name}` — runs it on ANOTHER app,
+     *    where `ref` is the app's **name** or uuid. A name is resolved by the
+     *    runtime deterministically (marketplace → custom); use the uuid to pin a
+     *    specific app. This is the addressing to use where there's no ambient
+     *    "current app" — e.g. a workflow, which has no per-install uuid to hardcode.
+     *
+     * `body` is sent as the POST body; `options.query` / `options.headers` are optional.
+     *
+     * The current app's uuid (bare-name form) is resolved automatically from the
+     * platform context (FORGE_APP_UUID for public views, forge_app_uuid in
+     * sessionStorage for platform views), so app code never needs its own uuid.
+     *
+     * Resolving the app does NOT grant access. Execution is still authorized against
+     * the caller's permissions — for a `platform`-access service the caller must hold
+     * `execute forge::service::{appUuid}::{name}`; `public`-access services require none.
+     */
+    async runService(target, body, options) {
+        var _a;
+        const { ref, serviceName } = parseServiceTarget(target);
         const queryString = (options === null || options === void 0 ? void 0 : options.query)
             ? '?' + new URLSearchParams(options.query).toString()
             : '';
         // @ts-ignore
         const devServiceUrl = isBrowser && ((_a = window.__ENV_VARIABLES__) === null || _a === void 0 ? void 0 : _a.FORGE_DEV_SERVICE_URL);
         if (devServiceUrl) {
-            return axios.post(`${devServiceUrl}/${serviceName}${queryString}`, (_b = options === null || options === void 0 ? void 0 : options.body) !== null && _b !== void 0 ? _b : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+            // The dev service server routes by name; the ref is ignored.
+            return axios.post(`${devServiceUrl}/${serviceName}${queryString}`, body !== null && body !== void 0 ? body : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+        }
+        if (!ref) {
+            throw new Error("runService: could not resolve the current app from the platform context. " +
+                "Use a service PRN with an explicit ref: prn:forge:{name|uuid}:service/{serviceName}.");
         }
-        return await this.client.post(`/luma/forge-runtime/api/services/${appUuid}/${serviceName}${queryString}`, (_c = options === null || options === void 0 ? void 0 : options.body) !== null && _c !== void 0 ? _c : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
+        // Service execution is owned by the forge runtime (forge-runtime gateway ->
+        // platform-forge), which resolves the ref (name → uuid, marketplace → custom)
+        // and executes the service, enforcing `execute forge::service::{uuid}::{name}`
+        // for platform-access services before running.
+        return await this.client.post(`/luma/forge-runtime/api/services/${ref}/${serviceName}${queryString}`, body !== null && body !== void 0 ? body : {}, (options === null || options === void 0 ? void 0 : options.headers) ? { headers: options.headers } : undefined);
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptkl/sdk",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",