3DN SDK

Secure, scalable, developer friendly

These are requirements for the package, not aspirations: each one gets a test before 1.0. Where a requirement and a convenience conflict, the requirement wins.

// createBuilder() refuses configuration that would leak a secret or load foreign code.
createBuilder({ installationKey: 'tdn_inst_…' });          // → CONFIG_INVALID
createBuilder({ scriptUrl: 'https://cdn.example/x.js' });  // → CONFIG_INVALID
createBuilder({ version: '../../evil' });                  // → CONFIG_INVALID

// Allowed: an approved environment and an exact or 'latest' version.
createBuilder({ environment: 'staging', version: 'latest', session, login });

Hosts with a Content-Security-Policy get the exact allowlist for their environment from 3DN during onboarding.

npm install @3dn-builder/builder

Create, mount, save

createBuilder() creates an SDK controller and records host callbacks. It does not call those callbacks, load the builder script, or modify the page until the host calls load() or mount(). The host supplies three backend calls (session, login token, customization) and its own login UI; the SDK does everything else.

import { createBuilder } from '@3dn-builder/builder';

const builder = createBuilder({
  environment: 'production',
  version: 'latest',
  session: {
    // Site access, plus which 3DN product this shopper should open.
    get: ({ hostProductId }) => backend.getBuilderSession(hostProductId),
    refreshLicense: () => backend.refreshBuilderLicense(),
  },
  login: {
    // Shopper identity, only when the builder asks for it. null on 401.
    getTokens: () => backend.mintBuilderTokens(),
    onRequired: (action) => showLogin(action), // 'logged-in' | 'redirected' | 'cancelled'
  },
  customization: {
    // The SDK calls this when a save created the shopper's clone.
    record: (link) => backend.recordCustomization(link),
  },
  onLicenseError: (error) => reportSetupError(error.code),
  onCloseRequested: ({ hasUnsavedChanges }) => closeModal({ confirm: hasUnsavedChanges }),
});

const container = document.querySelector<HTMLElement>('#builder-container');
if (!container) throw new Error('Missing #builder-container');

// Mount with the host's own product reference, never a raw 3DN id.
await builder.mount({ target: container, hostProductId: shopProduct.id, mode: 'designer' });

customizeButton.addEventListener('click', () => {
  showModal();
  builder.open();
});

// Add to cart: when save() resolves, the design is saved and any clone
// mapping is already recorded. design.productId is the one for the cart.
const design = await builder.save();
await cart.add({ variantId, properties: { threednProductId: design.productId } });

Site access and shopper identity stay separate

The SDK intentionally keeps site access and shopper identity separate. The session/license token lets a storefront load the builder. Shopper tokens are added only when the builder needs a logged-in shopper for a protected action such as save, upload, export, or share.

// Layer 1, site access. Every visitor, guest or not.
el.setAttribute('license-token', session.licenseToken);

// Layer 2, shopper identity. Only once a shopper is known.
el.setAttribute('refresh-token', tokens.refreshToken);
el.setAttribute('bearer-token', tokens.token);

// Logout or shopper switch: remove layer 2, keep layer 1.
el.removeAttribute('bearer-token');
el.removeAttribute('refresh-token');

The host names its product, the backend picks the 3DN product

The SDK should not force the storefront browser to know which 3DN product should open. The host passes its own product reference, and the host backend translates that into the correct 3DN product id for the current shopper.

Global product to shopper clone

• A global product is the original 3DN product the merchant embeds. Opening it never creates a clone.
• A guest, or a logged-in shopper who has never saved this product, opens the global product.
• The first save of a global product creates a shopper-specific 3DN clone. The builder and 3DN perform the clone, not the host, and the clone belongs to the shopper under the merchant's license.
• The builder then switches to the clone, so every later save updates it instead of creating another one.
• Opening a product that is already the shopper's clone and saving it updates that clone.

The first save of a global product creates a shopper-specific 3DN clone. The builder returns the cloned product id through the clone event. The host records that mapping so future sessions for the same shopper and host product can open the clone directly.

What the product detail page opens

The product detail page does not always open the global 3DN product. For a logged-in shopper who already saved a customized clone, the session should return that clone id. Otherwise, it returns the global product id. The decision belongs in the session response, not in browser logic.

// GET /threedn/session?product=<hostProductId>   (your path, your names)

// Guest, or a logged-in shopper with no saved clone: the global product.
{ "licenseToken": "…", "productId": "<global 3DN product id>", "viewToken": "…" }

// Logged-in shopper who already saved a clone for this host product.
{ "licenseToken": "…", "productId": "<shopper's clone id>",
  "token": "…", "refreshToken": "…" }   // optional fast path

Recording the clone mapping

The host does not handle the clone itself. It supplies customization.record(), a call to its customization endpoint, and the SDK calls it when a save created a clone. When save() resolves, that has already happened. The host's backend stores one row per shopper and host product: the shopper, the host product id, the global 3DN product id, and the clone id.

// What the SDK passes to customization.record() when a save created a clone.
link = {
  hostProductId: 'alpine-mug-12oz',    // your catalog reference
  sourceProductId: '<global 3DN id>',   // originalProductId
  savedProductId: '<clone 3DN id>',     // newProductId
};

// Your backend upserts one row per (shopper, hostProductId).
// The shopper comes from YOUR server session, never from the request body.
upsert({ shopper: req.user.id, ...link });

// Inside the SDK: how save() settles. Hosts never see this branching.
el.dispatchEvent(new CustomEvent('tdn-save-request'));
startTimer(saveTimeoutMs);            // 45 s by default, paused during a login round-trip

on('tdn-design-saved', async ({ productId, version }) => {
  if (productId !== currentProductId) {
    // The save created a clone. tdn-product-cloned follows the thumbnail
    // upload, so wait for it before resolving.
    const clone = await once('tdn-product-cloned');
    pendingLink = {
      hostProductId,
      sourceProductId: clone.originalProductId,
      savedProductId: clone.newProductId,
    };
    currentProductId = clone.newProductId; // later saves update the clone
  }
  if (pendingLink) {
    try {
      await config.customization.record(pendingLink);
      pendingLink = null;
    } catch (cause) {
      // Saved, but not linked. A retried save() re-runs record() only.
      return reject(new BuilderError('SAVE_FAILED', { reason: 'customization', retryable: true, cause }));
    }
  }
  resolve({ productId, version });      // productId: always the one to put in the cart
});
on('tdn-design-save-failed', (detail) => reject(toBuilderError(detail)));
onTimeout(() => reject(new BuilderError('SAVE_TIMEOUT', { retryable: true })));

Two callbacks, two different questions

session.get() opens or refreshes the builder session. login.getTokens() answers tdn-login-required. The initial session may already include shopper tokens as a fast path, but the login-token call remains the explicit answer whenever the builder asks for a logged-in shopper.

Each callback maps to one endpoint on the host backend. Paths are the host's choice. All three answer with Cache-Control: no-store, and the SDK never talks to the 3DN API with a key.

Designer, display-only, and private products

Not every embed is the full designer. Hosts can use display-only mode for previews and read-only views. When the product is private, the session must include a view token so the builder can load it safely.

External export: opt-in, always answered

External export is an opt-in SDK feature. If enabled, the host must return the generated file result or the SDK must complete the request with a failure or timeout. The builder must never be left waiting indefinitely.

• Off by default. A host receives export requests only when it passes externalExport to mount().
• Only for imported 3D model (GLB) products. Dieline products always export through 3DN.
• The host's run() returns the files; the SDK sends the reply to the builder.
• If run() rejects, or takes longer than timeoutMs (120 seconds by default, configurable per mount), the SDK aborts it and replies with EXPORT_FAILED or EXPORT_TIMEOUT.

// Inside the SDK, only when the host passed externalExport. The builder has
// no timeout of its own, so the SDK always replies: files, or an error.
on('exportRequested', async (request) => {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), externalExport.timeoutMs ?? 120_000);
  try {
    const files = await externalExport.run(request, controller.signal);
    reply({ files });
  } catch {
    const code = controller.signal.aborted ? 'EXPORT_TIMEOUT' : 'EXPORT_FAILED';
    reply({ files: [], error: { code } });  // needs builder prerequisite 1
  } finally {
    clearTimeout(timer);
  }
});

Host callbacks and responses

The callbacks are the host's own functions. They are not built into the SDK and are not passed through to the web component. Login uses its own login.getTokens() callback rather than calling session.get() again, because pre-minting shopper tokens in the session endpoint is optional under the host contract: a session endpoint that does not pre-mint would return no tokens after a login.

type BuilderEnvironment = 'production' | 'staging';
type BuilderVersion = 'latest' | `${number}.${number}.${number}`;
type BuilderMode = 'designer' | 'viewer';

/** What your session endpoint returns. Site access plus the product to open. */
interface BuilderSession {
  licenseToken: string;
  /** The 3DN product to open: the shopper's clone, else the global product. */
  productId: string;
  /** Required when the product to open is private. */
  viewToken?: string;
  /** Optional fast path: shopper tokens for a shopper your backend verified. */
  token?: string;
  refreshToken?: string;
}

/** Shopper identity, from your login-token endpoint. */
interface ShopperTokens {
  token: string;
  refreshToken: string;
}

type LoginOutcome = 'logged-in' | 'redirected' | 'cancelled';

interface CustomizationLink {
  hostProductId: string;
  sourceProductId: string;
  savedProductId: string;
}

interface BuilderHostConfig {
  environment?: BuilderEnvironment; // default 'production'
  version?: BuilderVersion;         // default 'latest'
  saveTimeoutMs?: number;           // default 45_000
  session: {
    get(request: { hostProductId: string }): Promise<BuilderSession>;
    refreshLicense(): Promise<Pick<BuilderSession, 'licenseToken'>>;
  };
  login?: {
    /** Answers tdn-login-required. null means 401: no shopper is logged in. */
    getTokens(): Promise<ShopperTokens | null>;
    /** Your login UX for the action the builder gated. */
    onRequired(action: LoginRequiredAction): Promise<LoginOutcome>;
    /** getTokens() failed (5xx, network). Default: 'cancel'. */
    onMintFailed?(): Promise<'retry' | 'cancel'>;
  };
  customization?: {
    record(link: CustomizationLink): Promise<void>;
  };
  onLicenseError?(error: BuilderError): void;
  onCloseRequested?(detail: CloseRequestedDetail): void;
  onStatusChange?(detail: BuilderStatusDetail): void;
  /** Lifecycle logging to the console. Tokens are always redacted. */
  debug?: boolean;
}

interface MountOptions {
  target: HTMLElement;
  /** Your own product reference, passed to session.get(). Never a 3DN id. */
  hostProductId: string;
  mode?: BuilderMode; // 'viewer' sets display-only="true"
  designId?: string;
  /** Opt-in, GLB products only. Off unless this is passed. */
  externalExport?: {
    run(request: ExportRequestedDetail, signal: AbortSignal): Promise<ExportFile[]>;
    timeoutMs?: number; // default 120_000
  };
}

The event detail types are the builder's own. The SDK re-exports them from a separate ./events entry point so a host can type its own listeners without pulling in the loader.

// Re-exported from '@3dn-builder/builder/events', matching the builder.
type LoginRequiredAction = 'save' | 'screenshot' | 'export' | 'upload' | 'share' | 'session';
type LicenseErrorCode = 'ORIGIN_NOT_ALLOWED' | 'LICENSE_TOKEN_INVALID';
type DesignSaveFailureReason =
  | 'conflict' | 'forbidden' | 'unauthorized' | 'login-cancelled'
  | 'installation-inactive' | 'license' | 'error';

interface DesignSavedDetail { productId: string; version: number }
interface DesignSaveFailedDetail { productId?: string; reason: DesignSaveFailureReason; retryable: boolean }
interface ProductClonedDetail { originalProductId: string; newProductId: string; name: string; asCopy: boolean }
interface CloseRequestedDetail { productId?: string; hasUnsavedChanges: boolean }
interface BuilderStatusDetail { status: 'idle' | 'opening' | 'loading' | 'ready' | 'error'; step?: string; message?: string; error?: string }
interface ExportRequestedDetail { productId: string; formats: string[]; surfaces: string[]; mode?: string }
interface ExportFile { url: string; format: string; surface: string }
interface ExportCompleteDetail { files: ExportFile[] }
// Proposed builder addition (prerequisite 1): error?: { code: 'EXPORT_FAILED' | 'EXPORT_TIMEOUT' }

Runtime methods

Event binding and attribute order in mount()

The SDK binds listeners before connecting the builder element and applies required attributes before load begins. This prevents missed events and avoids starting the builder with incomplete session data. Within the shopper pair, refresh-token goes before bearer-token, because setting the bearer token resumes a pending action.

1. Create the builder element.
2. Attach event listeners.
3. Set the 3DN product id from the session.
4. Set the license token.
5. Set the view token, if the session returned one.
6. Set the shopper refresh and bearer tokens, if the session returned them.
7. Set mode flags such as display-only and external-export.
8. Insert the element into the target container. Loading starts here.

// What mount() does, in this order. Nothing is connected until step 8.
await loader.load(environment, version);       // once per page
const session = await config.session.get({ hostProductId });

const el = document.createElement('threed-builder');              // 1
attachListeners(el);                                               // 2  no early event is missed
el.setAttribute('product', session.productId);                     // 3
el.setAttribute('license-token', session.licenseToken);            // 4
if (session.viewToken) el.setAttribute('view-token', session.viewToken);   // 5
if (session.token) {                                               // 6
  el.setAttribute('refresh-token', session.refreshToken);          //    refresh first,
  el.setAttribute('bearer-token', session.token);                  //    then bearer
}
if (designId) el.setAttribute('design-id', designId);
if (mode === 'viewer') el.setAttribute('display-only', 'true');    // 7
if (externalExport) el.setAttribute('external-export', 'true');
target.appendChild(el);                                            // 8  load starts here

Every login request gets one answer

When a guest presses Save (or screenshot, export, upload, share), or the builder cannot refresh its session, it fires tdn-login-required once and waits. The SDK must end every round-trip with either user tokens on the element or tdn-login-cancelled, except when the host redirected to a login page: then it sends neither.

// How the SDK answers tdn-login-required: exactly one answer per request.
async function onLoginRequired(action) {
  if (pending) return;                       // one round-trip at a time
  pending = true;
  try {
    for (;;) {
      let tokens;
      try {
        tokens = await config.login.getTokens();
      } catch {
        // 5xx or network: offer a retry, never a login.
        if ((await config.login.onMintFailed?.()) === 'retry') continue;
        return cancel(action);
      }
      if (tokens) return setShopperTokens(el, tokens); // resumes the action

      const outcome = await config.login.onRequired(action);
      if (outcome === 'logged-in') continue;  // dialog login: mint now
      if (outcome === 'redirected') return;   // never cancel on redirect
      return cancel(action);                  // dispatches tdn-login-cancelled
    }
  } finally {
    pending = false;
  }
}

Login by redirect

Most platforms log in on a separate page. Before firing tdn-login-required for a save, the builder has already written the design to the device, marked "save pending". The host redirects with a relative return path carrying the tdn_resume=1 marker and resolves 'redirected'. Back on the product page the SDK strips the marker, the host mounts the same source product, its session now includes user tokens, and the builder restores the draft and runs the pending save by itself.

import { consumeResumeMarker, hasDraft } from '@3dn-builder/builder';

// Back from the login page: reopen the same host product.
// The builder restores the draft and runs the pending save itself.
if (consumeResumeMarker()) await openDesigner();

// Shopper came back later: offer to continue the draft kept on this device.
if (hasDraft(sourceProductId)) showResumeButton(openDesigner);

Bridge the current builder contract

The SDK wraps the web component's existing events and adds no undocumented signals. The SDK listens on the element it created and dispatches its own events on that same element, so two builders on one page never answer each other.

One error shape for every failure

Every SDK failure should resolve to a stable BuilderError. Hosts should not need to parse raw DOM events to understand whether a failure is retryable, fatal, user-cancelled, or an export timeout. Each error carries a stable code, a message that is safe to show or log, and the builder's original reason for debugging.

type BuilderErrorCode =
  | 'CONFIG_INVALID'    // bad option, or a secret passed to the browser
  | 'NOT_IN_BROWSER'    // load() or mount() called during SSR
  | 'LOAD_FAILED'       // the builder script did not load
  | 'VERSION_CONFLICT'  // another builder version already owns the page
  | 'SESSION_FAILED'    // session.get() rejected
  | 'LICENSE_ERROR'     // tdn-license-error: fatal for this mount
  | 'LOGIN_CANCELLED'   // the protected action ended because login was cancelled
  | 'SAVE_FAILED'       // tdn-design-save-failed, see reason
  | 'SAVE_TIMEOUT'      // no save outcome within saveTimeoutMs
  | 'EXPORT_FAILED'     // externalExport.run() rejected
  | 'EXPORT_TIMEOUT'    // externalExport.run() exceeded its timeout
  | 'DESTROYED';        // the instance was destroyed mid-call

class BuilderError extends Error {
  readonly code: BuilderErrorCode;
  /** Safe to show in host UI or logs. Never contains a token. */
  readonly message: string;
  readonly retryable: boolean;
  /** The mount cannot continue until the host refreshes or recreates it. */
  readonly fatal: boolean;
  /** The builder's own reason, kept for debugging. */
  readonly reason?: DesignSaveFailureReason | LicenseErrorCode | 'customization';
  /** The raw event detail, tokens redacted. */
  readonly cause?: unknown;
}

try {
  await builder.save();
} catch (e) {
  if (!(e instanceof BuilderError)) throw e;
  if (e.code === 'LOGIN_CANCELLED') return;            // shopper chose not to log in
  showMessage(e.message, { retry: e.retryable });
}

Error codes

Builder save reasons

The builder's tdn-design-save-failed reason is kept on the error as reason, together with the event's own retryable flag.

Package exports and versioning

The SDK package version and the builder version solve different problems. The SDK version covers the adapter API installed by the host. The builder version selects which builder release the adapter loads.

{
  "name": "@3dn-builder/builder",
  "version": "0.1.0",
  "type": "module",
  "sideEffects": false,
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./events": {
      "types": "./dist/events.d.ts",
      "import": "./dist/events.js"
    },
    "./testing": {
      "types": "./dist/testing.d.ts",
      "import": "./dist/testing.js"
    }
  },
  "dependencies": {},
  "files": ["dist", "README.md", "LICENSE"]
}

Build the SDK in small modules

Still open

• The two builder prerequisites for external export (an error reply, and absolute file URLs).
• The staging builder location the SDK maps environment: 'staging' to, confirmed before release.
• Whether the SDK offers a confirm-on-back helper for full-screen hosts, or leaves it to each host.
• Whether the SDK reports ORIGIN_NOT_ALLOWED to the host backend itself, through an optional callback.
• Whether to add a builder "thumbnail ready" event before 1.0, so hosts stop reading load progress as a save.