@kmlckj/licos-platform-sdk 0.8.6 → 0.9.0

package/README.md

@@ -161,25 +161,52 @@ Use `uns.openPath(path)` when business code targets an existing enterprise UNS
 path without creating or changing `UNS.json`:
 
 ```js
-const temperature = uns.openPath('project:/production-line/temperature');
-const current = await temperature.pointCurrent();
-```
+const temperature = uns.openPath('project:/production-line/temperature');
+const current = await temperature.pointCurrent();
+```
+
+Realtime point consumers obtain the server-side WebSocket endpoint through the
+authorized project runtime API. Create one upstream connection per returned
+`nodeCode`; do not derive or hardcode a DataFactory address:
+
+```js
+const realtime = await uns.pointRealtimeConfig('TEMP_01');
+// Connect to realtime.websocketUrl and register with realtime.nodeCode.
+```
+
+Resource apply, data writes, point writes, and video controls require explicit
+confirmation. Data deletion accepts the exact rows returned by a prior query
+and also requires explicit confirmation. Point writes require a reason and ticket. The browser entry
+does not export UNS helpers.
+
+## Direct Industrial Integration
 
-Realtime point consumers obtain the server-side WebSocket endpoint through the
-authorized project runtime API. Create one upstream connection per returned
-`nodeCode`; do not derive or hardcode a DataFactory address:
+The server-only `industrial` facade manages collection and video resources
+without creating DataFactory UNS nodes. Use it only when the user explicitly
+selects direct collector integration; UNS failures must not trigger this mode.
 
 ```js
-const realtime = await uns.pointRealtimeConfig('TEMP_01');
-// Connect to realtime.websocketUrl and register with realtime.nodeCode.
+import { industrial } from '@kmlckj/licos-platform-sdk';
+
+const points = await industrial.searchResources('collectionPoint', {
+  scope: 'project',
+  keyword: 'temperature',
+});
+
+const current = await industrial.pointCurrent(points.items[0].id);
+const realtime = await industrial.realtimeConnection({
+  pointIds: [points.items[0].id],
+  transport: 'websocket',
+});
 ```
 
-Resource apply, data writes, point writes, and video controls require explicit
-confirmation. Data deletion accepts the exact rows returned by a prior query
-and also requires explicit confirmation. Point writes require a reason and ticket. The browser entry
-does not export UNS helpers.
-
-## OAuth2 Application Management
+Realtime subscription defaults to upstream WebSocket and supports explicitly
+selected MQTT. Point control defaults to HTTP and supports explicitly selected
+MQTT. Neither direction silently falls back. Resource writes use a reviewed
+`IndustrialChangeSet`; point and video writes require independent confirmation.
+The browser entry does not export industrial helpers or external credentials.
+
+## OAuth2 Application Management
 
 OAuth2 management is available only from trusted Node runtime code. It uses the
 current project owner's platform identity and is not exported by the browser

package/dist/index.d.ts

@@ -28,7 +28,8 @@ export interface RuntimeConfig {
 export function runtimeConfig(options?: { environmentOverrideEnv?: string }): Promise<RuntimeConfig>;
 export function authHeaders(config: RuntimeConfig, contentType?: string): Record<string, string>;
 
-export * from './uns.js';
+export * from './uns.js';
+export * from './industrial.js';
 
 export type OAuthLoginAudience = 'ALL' | 'OWNER_TENANT';
 

package/dist/index.js

@@ -1 +1 @@
-export{PlatformSdkError,ConfigurationError,ApiError}from"./shared.js";export{runtimeConfig,authHeaders}from"./runtime.js";export*from"./database.js";export*from"./knowledge.js";export*from"./oauth.js";export*from"./oauth-runtime.js";export*from"./storage.js";export*from"./uns.js";export{studioDatabase}from"./studio-database.js";
+export{PlatformSdkError,ConfigurationError,ApiError}from"./shared.js";export{runtimeConfig,authHeaders}from"./runtime.js";export*from"./database.js";export*from"./knowledge.js";export*from"./industrial.js";export*from"./oauth.js";export*from"./oauth-runtime.js";export*from"./storage.js";export*from"./uns.js";export{studioDatabase}from"./studio-database.js";

package/dist/industrial.d.ts

@@ -0,0 +1,120 @@
+export type IndustrialResourceType =
+  | 'edgeAgent'
+  | 'connection'
+  | 'collectionTask'
+  | 'collectionPoint'
+  | 'videoEdge'
+  | 'videoGateway'
+  | 'videoDevice'
+  | 'videoChannel';
+
+export type IndustrialSubscriptionTransport = 'auto' | 'websocket' | 'mqtt';
+export type IndustrialControlTransport = 'auto' | 'http' | 'mqtt';
+
+export function getIndustrialProtocolSchema(protocol: string): Promise<Record<string, unknown>>;
+export function searchIndustrialResources(
+  resourceType: IndustrialResourceType | string,
+  options?: {
+    protocol?: string;
+    keyword?: string;
+    scope?: 'project' | 'enterprise';
+    selector?: Record<string, unknown>;
+    page?: number;
+    pageSize?: number;
+    page_size?: number;
+  },
+): Promise<Record<string, unknown>>;
+export function getIndustrialResource(
+  resourceType: IndustrialResourceType | string,
+  resourceId: string,
+): Promise<Record<string, unknown>>;
+export function validateIndustrialChanges(document: Record<string, unknown>): Promise<Record<string, unknown>>;
+export function planIndustrialChanges(document: Record<string, unknown>): Promise<Record<string, unknown>>;
+export function applyIndustrialChanges(
+  document: Record<string, unknown>,
+  options: {
+    expectedDocumentHash?: string;
+    expected_document_hash?: string;
+    expectedPlanHash?: string;
+    expected_plan_hash?: string;
+    confirmed: boolean;
+    impactConfirmed?: boolean;
+    impact_confirmed?: boolean;
+  },
+): Promise<Record<string, unknown>>;
+export function getIndustrialRuntimeCapabilities(): Promise<Record<string, unknown>>;
+export function getIndustrialRealtimeConnection(options: {
+  pointIds?: string[];
+  point_ids?: string[];
+  tagCodes?: string[];
+  tag_codes?: string[];
+  transport?: IndustrialSubscriptionTransport;
+}): Promise<{
+  url: string;
+  authentication: string;
+  subscribe: {
+    type: 'subscribe';
+    transport: IndustrialSubscriptionTransport;
+    pointIds: string[];
+    tagCodes: string[];
+  };
+}>;
+export function getIndustrialPointCurrent(pointId: string): Promise<Record<string, unknown>>;
+export function getIndustrialPointHistory(
+  pointId: string,
+  options: {
+    startTime?: string;
+    start_time?: string;
+    endTime?: string;
+    end_time?: string;
+    page?: number;
+    pageSize?: number;
+    page_size?: number;
+  },
+): Promise<Record<string, unknown>>;
+export function writeIndustrialPoint(
+  pointId: string,
+  value: unknown,
+  options: {
+    reason: string;
+    ticket: string;
+    transport?: IndustrialControlTransport;
+    requestId?: string;
+    request_id?: string;
+    dryRun?: boolean;
+    dry_run?: boolean;
+    confirmed?: boolean;
+  },
+): Promise<Record<string, unknown>>;
+export function getIndustrialVideoStreamOptions(channelId: string): Promise<Record<string, unknown>>;
+export function startIndustrialVideoPreview(
+  channelId: string,
+  options: {
+    confirmed: boolean;
+    preferredProtocol?: string;
+    preferred_protocol?: string;
+    preferredProtocolOrder?: string[];
+    preferred_protocol_order?: string[];
+  },
+): Promise<Record<string, unknown>>;
+export function stopIndustrialVideoPreview(
+  channelId: string,
+  options: { confirmed: boolean },
+): Promise<Record<string, unknown>>;
+
+export const industrial: {
+  protocolSchema: typeof getIndustrialProtocolSchema;
+  searchResources: typeof searchIndustrialResources;
+  resource: typeof getIndustrialResource;
+  validateChanges: typeof validateIndustrialChanges;
+  planChanges: typeof planIndustrialChanges;
+  applyChanges: typeof applyIndustrialChanges;
+  runtimeCapabilities: typeof getIndustrialRuntimeCapabilities;
+  realtimeConnection: typeof getIndustrialRealtimeConnection;
+  pointCurrent: typeof getIndustrialPointCurrent;
+  pointHistory: typeof getIndustrialPointHistory;
+  writePoint: typeof writeIndustrialPoint;
+  videoStreamOptions: typeof getIndustrialVideoStreamOptions;
+  startVideoPreview: typeof startIndustrialVideoPreview;
+  stopVideoPreview: typeof stopIndustrialVideoPreview;
+};

package/dist/industrial.js

@@ -0,0 +1 @@
+import{ApiError as t}from"./shared.js";import{authHeaders as e,refreshRuntimeConfig as r,runtimeConfig as n,shouldRefreshUserToken as i}from"./runtime.js";function o(t){return Object.fromEntries(Object.entries(t).filter(([,t])=>null!=t))}function a(t,e){return`/projects/${encodeURIComponent(t.projectId)}${e}`}async function s(a,s,{body:c,config:d}={}){let u=d||await n();for(let n=0;n<2;n+=1)try{const r=await fetch(new URL(`${u.baseUrl}/api/v1${s}`),{method:a,headers:e(u,void 0===c?void 0:"application/json"),body:void 0===c?void 0:JSON.stringify(o(c))}),n=await r.text();let i=null;try{i=n?JSON.parse(n):null}catch{throw new t(n||`platform industrial API returned ${r.status}`,{status:r.status,details:n})}if(!r.ok||i&&void 0!==i.code&&0!==i.code||!1===i?.success)throw new t(i?.message||n||"platform industrial API failed",{status:r.status,code:"number"==typeof i?.code?i.code:void 0,details:i});return i&&"object"==typeof i?i.data:i}catch(t){if(0===n&&i(t)){u=await r(u);continue}throw t}throw new t("platform industrial API failed")}export async function getIndustrialProtocolSchema(t){const e=await n();return s("GET",a(e,`/industrial/protocols/${encodeURIComponent(t)}/schema`),{config:e})}export async function searchIndustrialResources(t,e={}){const r=await n();return s("POST",a(r,"/industrial/resources/search"),{body:{resourceType:t,protocol:e.protocol,keyword:e.keyword,scope:e.scope||"project",selector:e.selector||{},page:e.page??1,pageSize:e.pageSize??e.page_size??20},config:r})}export async function getIndustrialResource(t,e){const r=await n();return s("GET",a(r,`/industrial/resources/${encodeURIComponent(t)}/${encodeURIComponent(e)}`),{config:r})}async function c(t,e){const r=await n();return s("POST",a(r,`/industrial/changes/${t}`),{body:{document:e},config:r})}export function validateIndustrialChanges(t){return c("validate",t)}export function planIndustrialChanges(t){return c("plan",t)}export async function applyIndustrialChanges(t,e={}){const r=String(e.expectedDocumentHash??e.expected_document_hash??"").trim(),i=String(e.expectedPlanHash??e.expected_plan_hash??"").trim();if(!0!==e.confirmed)throw new TypeError("industrial changes apply requires explicit confirmation");if(!r||!i)throw new TypeError("industrial changes apply requires document and plan hashes");const o=await n();return s("POST",a(o,"/industrial/changes/apply"),{body:{document:t,expectedDocumentHash:r,expectedPlanHash:i,confirmed:!0,impactConfirmed:!0===e.impactConfirmed||!0===e.impact_confirmed},config:o})}export async function getIndustrialRuntimeCapabilities(){const t=await n();return s("GET",a(t,"/industrial/runtime/capabilities"),{config:t})}export async function getIndustrialRealtimeConnection(t={}){const e=(t.pointIds||t.point_ids||[]).map(String).map(t=>t.trim()).filter(Boolean),r=(t.tagCodes||t.tag_codes||[]).map(String).map(t=>t.trim()).filter(Boolean);if(0===e.length&&0===r.length)throw new TypeError("pointIds or tagCodes must be provided");const i=await n(),o=new URL(i.baseUrl);return o.protocol="https:"===o.protocol?"wss:":"ws:",o.pathname=`/api/v1${a(i,"/industrial/runtime/points/realtime")}`,o.search="",o.hash="",{url:o.toString(),authentication:"use platform session or Authorization header",subscribe:{type:"subscribe",transport:t.transport||"auto",pointIds:e,tagCodes:r}}}function d(t,e,r){return a(t,`/industrial/runtime/points/${encodeURIComponent(e)}/${r}`)}export async function getIndustrialPointCurrent(t){const e=await n();return s("GET",d(e,t,"current"),{config:e})}export async function getIndustrialPointHistory(t,e={}){const r=await n();return s("POST",d(r,t,"history"),{body:{startTime:e.startTime??e.start_time,endTime:e.endTime??e.end_time,page:e.page??1,pageSize:e.pageSize??e.page_size??100},config:r})}export async function writeIndustrialPoint(t,e,r={}){const i=String(r.reason||"").trim(),o=String(r.ticket||"").trim(),a=!0===r.dryRun||!0===r.dry_run;if(!a&&!0!==r.confirmed)throw new TypeError("industrial point write requires explicit confirmation");if(!i||!o)throw new TypeError("industrial point write requires reason and ticket");const c=await n();return s("POST",d(c,t,"write"),{body:{value:e,transport:r.transport||"auto",reason:i,ticket:o,requestId:r.requestId??r.request_id,dryRun:a,confirmed:!0===r.confirmed},config:c})}async function u(t,e,r,i){const o=await n();return s(t,a(o,`/industrial/runtime/video/channels/${encodeURIComponent(e)}/${r}`),{body:i,config:o})}export function getIndustrialVideoStreamOptions(t){return u("GET",t,"stream-options")}export function startIndustrialVideoPreview(t,e={}){if(!0!==e.confirmed)throw new TypeError("industrial video preview start requires explicit confirmation");return u("POST",t,"preview/start",{preferredProtocol:e.preferredProtocol??e.preferred_protocol??"http-flv",preferredProtocolOrder:e.preferredProtocolOrder??e.preferred_protocol_order??["http-flv","webrtc","hls"],confirmed:!0})}export function stopIndustrialVideoPreview(t,e={}){if(!0!==e.confirmed)throw new TypeError("industrial video preview stop requires explicit confirmation");return u("POST",t,"preview/stop",{confirmed:!0})}export const industrial={protocolSchema:getIndustrialProtocolSchema,searchResources:searchIndustrialResources,resource:getIndustrialResource,validateChanges:validateIndustrialChanges,planChanges:planIndustrialChanges,applyChanges:applyIndustrialChanges,runtimeCapabilities:getIndustrialRuntimeCapabilities,realtimeConnection:getIndustrialRealtimeConnection,pointCurrent:getIndustrialPointCurrent,pointHistory:getIndustrialPointHistory,writePoint:writeIndustrialPoint,videoStreamOptions:getIndustrialVideoStreamOptions,startVideoPreview:startIndustrialVideoPreview,stopVideoPreview:stopIndustrialVideoPreview};

package/dist/uns.d.ts

@@ -84,11 +84,11 @@ export function deleteUnsNodeData(nodeCode: string, rows: UnsObject[], options:
 export function queryUnsPathData(path: string, options?: UnsDataQueryOptions): Promise<UnsObject>;
 export function writeUnsPathData(path: string, fieldValues: UnsObject, options: { confirmed: boolean }): Promise<UnsObject>;
 export function deleteUnsPathData(path: string, rows: UnsObject[], options: { confirmed: boolean }): Promise<UnsObject>;
-export function getUnsPointCurrent(nodeCode: string): Promise<UnsObject>;
-export function getUnsPathPointCurrent(path: string): Promise<UnsObject>;
-export function getUnsPointRealtimeConfig(nodeCode: string): Promise<UnsObject>;
-export function getUnsPathPointRealtimeConfig(path: string): Promise<UnsObject>;
-export function getUnsPointHistory(nodeCode: string, options: UnsPointHistoryOptions): Promise<UnsObject>;
+export function getUnsPointCurrent(nodeCode: string): Promise<UnsObject>;
+export function getUnsPathPointCurrent(path: string): Promise<UnsObject>;
+export function getUnsPointRealtimeConfig(nodeCode: string): Promise<UnsObject>;
+export function getUnsPathPointRealtimeConfig(path: string): Promise<UnsObject>;
+export function getUnsPointHistory(nodeCode: string, options: UnsPointHistoryOptions): Promise<UnsObject>;
 export function getUnsPathPointHistory(path: string, options: UnsPointHistoryOptions): Promise<UnsObject>;
 export function writeUnsPoint(nodeCode: string, value: unknown, options: UnsPointWriteOptions): Promise<UnsObject>;
 export function writeUnsPathPoint(path: string, value: unknown, options: UnsPointWriteOptions): Promise<UnsObject>;
@@ -105,10 +105,10 @@ export class UnsPathNode {
   resolve(): Promise<UnsObject>;
   queryData(options?: UnsDataQueryOptions): Promise<UnsObject>;
   writeData(fieldValues: UnsObject, options: { confirmed: boolean }): Promise<UnsObject>;
-  deleteData(rows: UnsObject[], options: { confirmed: boolean }): Promise<UnsObject>;
-  pointCurrent(): Promise<UnsObject>;
-  pointRealtimeConfig(): Promise<UnsObject>;
-  pointHistory(options: UnsPointHistoryOptions): Promise<UnsObject>;
+  deleteData(rows: UnsObject[], options: { confirmed: boolean }): Promise<UnsObject>;
+  pointCurrent(): Promise<UnsObject>;
+  pointRealtimeConfig(): Promise<UnsObject>;
+  pointHistory(options: UnsPointHistoryOptions): Promise<UnsObject>;
   writePoint(value: unknown, options: UnsPointWriteOptions): Promise<UnsObject>;
   videoStreamOptions(): Promise<UnsObject>;
   videoSnapshot(): Promise<UnsObject>;
@@ -139,11 +139,11 @@ export const uns: {
   queryPathData: typeof queryUnsPathData;
   writePathData: typeof writeUnsPathData;
   deletePathData: typeof deleteUnsPathData;
-  pointCurrent: typeof getUnsPointCurrent;
-  pathPointCurrent: typeof getUnsPathPointCurrent;
-  pointRealtimeConfig: typeof getUnsPointRealtimeConfig;
-  pathPointRealtimeConfig: typeof getUnsPathPointRealtimeConfig;
-  pointHistory: typeof getUnsPointHistory;
+  pointCurrent: typeof getUnsPointCurrent;
+  pathPointCurrent: typeof getUnsPathPointCurrent;
+  pointRealtimeConfig: typeof getUnsPointRealtimeConfig;
+  pathPointRealtimeConfig: typeof getUnsPathPointRealtimeConfig;
+  pointHistory: typeof getUnsPointHistory;
   pathPointHistory: typeof getUnsPathPointHistory;
   writePoint: typeof writeUnsPoint;
   writePathPoint: typeof writeUnsPathPoint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmlckj/licos-platform-sdk",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "LICOS platform SDK package shell for browser and Node runtimes",
   "author": "kmlckj",
   "type": "module",