@rasterex/viewer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aridian Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# Rasterex Viewer SDK
+
+Embed Rasterex Viewer in your web application with a small iframe-based SDK.
+
+The SDK mounts the viewer, opens files, controls tools, listens for viewer events, and provides TypeScript types for the public API.
+
+Full documentation: https://documentation.rasterex.com/
+
+## Install
+
+```sh
+npm install @rasterex/viewer
+```
+
+## Requirements
+
+Use the package from a bundled application such as Vite, Next.js, Angular, React, Vue, Webpack, or Rollup.
+
+Browsers cannot resolve npm package names directly from a plain `<script type="module">` file without a bundler or import map.
+
+The viewer container must have a real width and height before mounting.
+
+```html
+<div id="rx-viewer" style="width: 100%; height: 640px"></div>
+```
+
+## No Framework
+
+For a plain HTML page without a framework or bundler, install the package and add an import map before your module script.
+
+```html
+<div id="rx-viewer" style="width: 100%; height: 640px"></div>
+
+<script type="importmap">
+{
+  "imports": {
+    "@rasterex/viewer": "./node_modules/@rasterex/viewer/dist/index.js",
+    "@rasterex/viewer/demo-presets": "./node_modules/@rasterex/viewer/dist/demo-presets.js"
+  }
+}
+</script>
+
+<script type="module">
+  import { createViewer } from "@rasterex/viewer";
+
+  const viewer = createViewer({
+    container: "#rx-viewer"
+  });
+
+  await viewer.mount();
+  await viewer.ready();
+</script>
+```
+
+## Quick Start
+
+```ts
+import { createViewer } from "@rasterex/viewer";
+
+const viewer = createViewer({
+  container: "#rx-viewer"
+});
+
+await viewer.mount();
+await viewer.ready();
+```
+
+By default, the SDK loads:
+
+```txt
+https://beta.viewer.viewsoft.com
+```
+
+`targetOrigin` is derived from the viewer URL when it is not provided.
+
+## Open A File URL
+
+```ts
+await viewer.documents.open({
+  url: "https://pdfobject.com/pdf/sample.pdf",
+  displayName: "sample.pdf",
+  cacheId: "file_7f3a9c2_sample_pdf",
+  mime: "application/pdf"
+});
+```
+
+The file URL must be reachable by the viewer environment.
+
+`displayName` should include the file extension, for example `sample.pdf`.
+
+`cacheId` should be a stable file/content ID from your application or server, not the display file name. It lets the server reuse already processed content for the same file, which can make repeat opens faster.
+
+## Open A Browser File
+
+```ts
+const input = document.querySelector<HTMLInputElement>("#file-input");
+const file = input?.files?.[0];
+const fileId = "file_7f3a9c2_sample_pdf";
+
+if (file) {
+  await viewer.documents.openFile(file, {
+    cacheId: fileId
+  });
+}
+```
+
+## Mount And Open In One Call
+
+```ts
+import { createDocumentViewer } from "@rasterex/viewer";
+
+const viewer = await createDocumentViewer({
+  container: "#rx-viewer",
+  document: {
+    url: "https://pdfobject.com/pdf/sample.pdf",
+    displayName: "sample.pdf"
+  }
+});
+```
+
+## Custom Viewer URL
+
+Use `viewerUrl` for your hosted or on-premises viewer.
+
+```ts
+import { createViewer } from "@rasterex/viewer";
+
+const viewer = createViewer({
+  container: "#rx-viewer",
+  viewerUrl: "https://viewer.example.com",
+  targetOrigin: "https://viewer.example.com"
+});
+
+await viewer.mount();
+await viewer.ready();
+```
+
+If `targetOrigin` is omitted, the SDK uses `new URL(viewerUrl).origin`.
+
+## Tools
+
+```ts
+await viewer.tools.set({
+  group: "measurement",
+  action: "MEASURE_LENGTH",
+  enabled: true
+});
+
+viewer.tools.clear();
+```
+
+## Annotation Events
+
+```ts
+const unsubscribe = viewer.annotations.on("created", (event) => {
+  console.log(event.guid, event.data);
+});
+
+unsubscribe();
+```
+
+## Options
+
+```ts
+interface RasterexViewerOptions {
+  container: HTMLElement | string;
+  viewerUrl?: string;
+  targetOrigin?: string;
+  connectTimeoutMs?: number;
+  readyTimeoutMs?: number;
+  commandTimeoutMs?: number;
+  debug?: boolean;
+  iframeTitle?: string;
+  iframeClassName?: string;
+  iframeAttributes?: Record<string, string>;
+}
+```
+
+| Option | Description |
+| --- | --- |
+| `container` | DOM element or selector where the iframe is mounted. |
+| `viewerUrl` | Viewer URL to load. Defaults to `https://beta.viewer.viewsoft.com`. |
+| `targetOrigin` | Trusted origin for viewer messages. Defaults to the origin of `viewerUrl`. |
+| `connectTimeoutMs` | Timeout for iframe loading. |
+| `readyTimeoutMs` | Timeout while waiting for viewer readiness. |
+| `commandTimeoutMs` | Timeout for commands that wait for a viewer response. |
+| `debug` | Writes SDK diagnostics to `console.debug`. |
+| `iframeTitle` | Accessible iframe title. |
+| `iframeClassName` | CSS class applied to the iframe. |
+| `iframeAttributes` | Extra iframe attributes, for example `{ allow: "fullscreen" }`. |
+
+## Presets
+
+Presets are optional and are exported from a separate entrypoint.
+
+```ts
+import { createViewer } from "@rasterex/viewer";
+import { sandboxCanvas, takeoffDemo } from "@rasterex/viewer/demo-presets";
+
+const viewer = createViewer({
+  container: "#rx-viewer",
+  viewerUrl: sandboxCanvas.viewerUrl,
+  targetOrigin: sandboxCanvas.targetOrigin
+});
+```
+
+Takeoff is not loaded by default. Use `takeoffDemo` only when your app explicitly chooses that preset.
+
+## TypeScript
+
+Types are included.
+
+```ts
+import type {
+  DocumentOpenOptions,
+  RasterexViewerOptions,
+  ToolAction,
+  ToolGroup
+} from "@rasterex/viewer";
+```
+
+TypeScript will report invalid option names, unsupported tool actions, and wrong payload shapes at compile time.
+
+## Common APIs
+
+```ts
+await viewer.documents.open({ url: "/files/sample.pdf", displayName: "sample.pdf" });
+await viewer.tools.set({ group: "measurement", action: "MEASURE_LENGTH", enabled: true });
+viewer.tools.clear();
+viewer.annotations.select({ guid: "annotation-guid" });
+const snapshot = await viewer.layers.getLayers();
+const firstLayer = snapshot.layers[0];
+if (firstLayer?.index !== undefined) {
+  await viewer.layers.setLayerVisibility({ index: firstLayer.index, visible: false });
+}
+const blocks = await viewer.blocks.getBlocks();
+const firstBlock = blocks.blocks[0];
+if (firstBlock?.index !== undefined) {
+  await viewer.blocks.getBlockDetails({ index: firstBlock.index });
+  viewer.blocks.setBlockVisibility({ index: firstBlock.index, visible: false });
+}
+viewer.compare.compare({ backgroundUrl: "old.pdf", overlayUrl: "new.pdf" });
+viewer.styles.setGlobalAppearance({ strokeColor: "#164863" });
+viewer.diagnostics.on("transport.error", (event) => console.error(event.error));
+```
+
+## Cleanup
+
+Destroy the viewer when the page, route, or component no longer needs it.
+
+```ts
+viewer.destroy();
+```
+
+## License
+
+This npm SDK is licensed under the MIT License.
+
+The SDK embeds Rasterex Canvas/viewer deployments through an iframe. The Rasterex Canvas application, hosted services, server components, viewer assets, and customer deployments are not licensed by this SDK package and remain subject to their own licenses and agreements.
+
+## Supply Chain Security
+
+The SDK is designed to stay lightweight and air-gap friendly:
+
+- No runtime npm dependencies.
+- No install-time scripts.
+- No telemetry.
+- No CDN dependency.
+- No bundled Rasterex Canvas Angular application.
+
+Before publishing, maintainers should verify the package with:
+
+```sh
+npm audit --omit=dev
+npm audit
+npm pack --dry-run
+```
+
+See `SECURITY.md` for the vulnerability reporting policy and package security scope.

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+## Supported Package
+
+Security reports for this repository should focus on the npm SDK package.
+
+In scope:
+
+- The published SDK package contents.
+- SDK iframe creation, origin validation, and `postMessage` handling.
+- SDK command validation and public API behavior.
+- Package metadata, dependency declarations, and release artifacts.
+- Build and publish configuration used to release the SDK.
+
+Out of scope for this SDK package:
+
+- Rasterex Canvas application source code.
+- Hosted Rasterex viewer services.
+- Server components, storage, processing backends, and customer deployments.
+- Viewer assets or deployment configuration not shipped in this npm package.
+
+## Reporting A Vulnerability
+
+Report suspected vulnerabilities privately to the package maintainers.
+
+Include:
+
+- Affected package name and version.
+- Reproduction steps or proof of concept.
+- Expected and actual behavior.
+- Browser, framework, and Canvas deployment details when relevant.
+
+Do not open a public issue for an unpatched vulnerability.
+
+## Supply Chain Posture
+
+The SDK is intended to stay lightweight and air-gap friendly:
+
+- No runtime npm dependencies.
+- No install-time scripts.
+- No telemetry.
+- No CDN dependency.
+- No bundled Rasterex Canvas Angular application.
+- Production applications should pass an explicit `viewerUrl` for their hosted or on-premises Canvas deployment.
+
+Before publishing, maintainers should run:
+
+```sh
+npm audit --omit=dev
+npm audit
+npm pack --dry-run
+```
+
+Publishing should use npm provenance when the package is released from a supported CI environment.

package/dist/RasterexViewer.d.ts

@@ -0,0 +1,70 @@
+import { Diagnostics } from "./diagnostics.js";
+import { CanvasApi } from "./domains/CanvasApi.js";
+import { DocumentsApi } from "./domains/DocumentsApi.js";
+import { AnnotationsApi } from "./domains/AnnotationsApi.js";
+import { ToolsApi } from "./domains/ToolsApi.js";
+import { MeasurementsApi } from "./domains/MeasurementsApi.js";
+import { CompareApi } from "./domains/CompareApi.js";
+import { CollaborationApi } from "./domains/CollaborationApi.js";
+import { StylesApi } from "./domains/StylesApi.js";
+import { LayersApi } from "./domains/LayersApi.js";
+import { BlocksApi } from "./domains/BlocksApi.js";
+import type { RasterexViewerInfo, RasterexViewerOptions } from "./types.js";
+export declare class RasterexViewer {
+    private readonly container;
+    private readonly viewerUrl;
+    private readonly targetOrigin;
+    private readonly iframeTitle;
+    private readonly iframeClassName?;
+    private readonly iframeAttributes?;
+    private readonly connectTimeoutMs;
+    private readonly readyTimeoutMs;
+    private readonly commandTimeoutMs;
+    private readonly sdkInstanceId;
+    readonly diagnostics: Diagnostics;
+    readonly canvas: CanvasApi;
+    readonly documents: DocumentsApi;
+    readonly annotations: AnnotationsApi;
+    readonly tools: ToolsApi;
+    readonly measurements: MeasurementsApi;
+    readonly compare: CompareApi;
+    readonly collaboration: CollaborationApi;
+    readonly styles: StylesApi;
+    readonly layers: LayersApi;
+    readonly blocks: BlocksApi;
+    private state;
+    private iframe;
+    private mountPromise;
+    private readyPromise;
+    private readyCleanup;
+    private readyReject;
+    private messagingSession;
+    private canvasSessionId;
+    private canvasVersion;
+    private buildDate;
+    private capabilities;
+    private minimumSdkVersion;
+    private compatibility;
+    constructor(options: RasterexViewerOptions);
+    mount(): Promise<void>;
+    ready(): Promise<void>;
+    destroy(): void;
+    getIframe(): HTMLIFrameElement | null;
+    isMounted(): boolean;
+    getInfo(): RasterexViewerInfo;
+    private isViewerReadyMessage;
+    private createIframe;
+    private startMessaging;
+    private completeCanvasBrokerReady;
+    private completeProtocolReady;
+    private emitMountStarted;
+    private emitMountResolved;
+    private emitMountFailed;
+    private emitMountSlow;
+    private emitHandshakeSlow;
+    private emitCompatibilityWarning;
+    private emitHandshakeComplete;
+    private getCanvasBroker;
+    private resolveContainer;
+}
+//# sourceMappingURL=RasterexViewer.d.ts.map

package/dist/RasterexViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RasterexViewer.d.ts","sourceRoot":"","sources":["../src/RasterexViewer.ts"],"names":[],"mappings":"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"}