NoeVault Snip Developer Integration

NoeVault Snip Developer Integration

NoeVault Snip Developer Integration

NoeVault Snip Developer Integration Guide

Canonical reference: KitchenPro.Web
Package: @noevault/snap 1.1.3 · Marker PR-8.7E.4A
Contract family: snap-integration / snap-integration.v1

Integration principles

  1. Your application session is authoritative for who is using Snap in your app.
  2. Bootstrap is trusted and server-side. AppKey never reaches the browser.
  3. SupportTicket is the SoR. Do not invent a parallel ticket store.
  4. Reuse shared editor components. Do not fork annotation.
  5. ExternalRequester Model B — do not create NoeVault users on submit.
your-app/
  wwwroot/
    lib/noevault-snap/
      noevault-snap.umd.js
      noevault-snap.css
    js/
      your-app-snap.js          ← host adapter (see KitchenPro kitchenpro-snap.js)
  Controllers/ or routes/
    SnapBootstrap endpoint      ← BFF using AppKey server-side

Host adapter responsibilities

Responsibility Host SDK
App login / session Yes No
Fetch bootstrap with credentials Yes Consumes result
Mount launcher UI Yes Provides Snap UI host
Capture permissions (getDisplayMedia) Browser + host gesture Editor consumes image
Fail-closed when disabled/unauthorized Yes Surfaces deny codes

Bootstrap

The browser receives a browser-safe bootstrap projection (SnapBrowserBootstrap) including:

  • Contract / capability status
  • Tenant/solution context
  • UI + capture/redaction policies
  • Endpoint discovery
  • Experience configuration (categories, priorities, claim offer when enabled)

Anonymous callers must fail closed (KitchenPro: 401 SNAP_APP_SESSION_REQUIRED).

Initialize and mount

import {
  createNoeVaultSnap,
  SNAP_PACKAGE_VERSION,
  SNAP_BUILD_MARKER,
  SNAP_CONTRACT_VERSION
} from '@noevault/snap';
import '@noevault/snap/style.css';

// Or UMD: window.NoeVaultSnap.createNoeVaultSnap / .init

const snap = createNoeVaultSnap({
  // theme / callbacks as needed by your shell
});
await snap.initialize(bootstrap);
// mount launcher according to host conventions

Validate at runtime:

console.assert(NoeVaultSnap.SNAP_PACKAGE_VERSION === '1.1.3');
console.assert(NoeVaultSnap.SNAP_BUILD_MARKER === 'PR-8.7E.4A');
console.assert(NoeVaultSnap.SNAP_CONTRACT_VERSION === 'snap-integration.v1');

Shared components you should not reimplement

const {
  SnapScreenEditor,
  AnnotationSession,
  AttachmentPicker,
  createConversationPoller,
  validateRequestComposer,
  preflightAttachments
} = NoeVaultSnap;

Panel native Snap uses the same UMD via snap-screen-shared-editor.js.

Submit path expectations

Successful create yields a SupportTicket with:

  • Correct organisation + solution scope
  • Selected category from effective categories
  • Evidence attachments ticket-scoped
  • Empty UserUID on ExternalRequester attachment/comment actors

Conversation

Use createConversationPoller (soft poll). No SignalR for ticket conversation in v1.

Account claim (optional)

When bootstrap includes a claim offer (SnapClaimOffer), hosts may expose “Claim your support history” using requestAccountClaim APIs. Claiming does not rewrite historical ticket ExternalRequester ownership keys.

Testing checklist

Test Pass criteria
Anon bootstrap Fail closed
Auth bootstrap Valid bootstrap; launcher visible
Composer validation Required summary/details/category enforced
Capture + annotate Shared editor tools; expand/collapse preserves state
Submit Ticket in SoR; Model B actors
My Requests Continuity for same ExternalRequester
Actor display Not “(system)” for ExternalRequester comments