Wiki macro types

These types are public exports of @ones-open/node-sdk; import them with import type. Node SDK WikiMacroContext locates the backend publication target. See Web SDK macro types for full frontend context.

InstallationInfo

Installation callback data retained on the backend.

export interface InstallationInfo {
  installation_id: string
  shared_secret: string
  ones_base_url: string
}

Field	Type	Required	Description
installation_id	string	Yes	Current app installation ID
shared_secret	string	Yes	Base64-encoded callback secret, never sent to the frontend
ones_base_url	string	Yes	ONES base URL provided by the installation callback

WikiMacroContext

Context identifying an existing macro. All fields are required; validate and retain its association with business records on the backend.

export interface WikiMacroContext {
  protocolVersion: 2
  appId: string
  installationId: string
  macroKey: string
  teamId: string
  documentId: string
  cardUuid: string
}

Field	Type	Description
protocolVersion	Literal 2	Current macro protocol
appId	string	App ID
installationId	string	Must equal InstallationInfo.installation_id
macroKey	string	Declared macro identifier
teamId	string	Team containing the macro
documentId	string	Collaborative document ID, not the page ID
cardUuid	string	Static content card ID, not macro blockId

teamId and cardUuid are eight alphanumeric characters. appId, installationId, macroKey and documentId are 1–128 letters, digits, underscores or hyphens. Use runtime-provided values instead of generating identifiers. customData, scene, writable, pageId and blockId are not fields of this Node SDK type.

WikiMacroExportSpec

export type WikiMacroExportSpec =
  | { type: 'text'; data: string }
  | { type: 'link'; data: { title: string; url: string } }
  | { type: 'image'; data: string }

Entry	Field	Type	Required	Description
Text	type	Literal 'text'	Yes	Plain text entry
Text	data	string	Yes	Plain text without HTML parsing
Link	type	Literal 'link'	Yes	Link entry
Link	data.title	string	Yes	Link title
Link	data.url	string	Yes	Valid HTTP, HTTPS or mailto URL
Image	type	Literal 'image'	Yes	Image entry
Image	data	string	Yes	Nonempty Wiki document resource ID or valid HTTPS image URL

Document resource IDs cannot contain /, backslashes, ?, # or :. HTTPS images must remain accessible in sharing, mobile and exports. Image entries do not accept additional request headers.

At most 1000 static entries are allowed. The final deduplicated resource set, including image references, allows at most 1000 items. Combined serialized UTF-8 entries and final resource references must not exceed 1 MiB.

WikiMacroResourceFile

export interface WikiMacroResourceFile {
  name: string
  data: Uint8Array
}

Field	Type	Required	Description
name	string	Yes	Nonempty filename, at most 255 UTF-8 bytes, without separators, line breaks, null characters or double quotes
data	Uint8Array	Yes	Binary content, including Buffer; size above zero and at most 20 MiB

This is not a browser File and has no type, size or arrayBuffer fields. Size is determined by data.byteLength.

WikiMacroClient

import type { WikiMacroContext, WikiMacroInstance } from '@ones-open/node-sdk'

export interface WikiMacroClient {
  instance(context: WikiMacroContext): WikiMacroInstance
}

Binds synchronously; see Create a macro client and instance.

WikiMacroInstance

import type { WikiMacroExportSpec, WikiMacroResourceFile } from '@ones-open/node-sdk'

export interface WikiMacroInstance {
  uploadResource(file: WikiMacroResourceFile): Promise<string>
  saveExportSpec(exportSpec: WikiMacroExportSpec[], resources: string[]): Promise<void>
}

Method	Return value	Description
uploadResource	Promise<string>	Resource ID, not a download URL or original filename
saveExportSpec	Promise<void>	Confirms publication without returning context or update time

Type usage example

import type {
  InstallationInfo,
  WikiMacroClient,
  WikiMacroContext,
  WikiMacroExportSpec,
  WikiMacroInstance,
  WikiMacroResourceFile,
} from '@ones-open/node-sdk'

interface MacroPublication {
  installation: InstallationInfo
  context: WikiMacroContext
  content: WikiMacroExportSpec[]
  file?: WikiMacroResourceFile
}

function bindPublication(
  client: WikiMacroClient,
  publication: MacroPublication,
): WikiMacroInstance {
  return client.instance(publication.context)
}