Create a macro client and instance

wiki.macro

Create a client using installation callback data. This operation sends no request and does not open an edit dialog.

import { wiki } from '@ones-open/node-sdk'
import type { InstallationInfo, WikiMacroClient } from '@ones-open/node-sdk'

const createClient: (installationInfo: InstallationInfo) => WikiMacroClient = wiki.macro

Parameter	Type	Required	Description
installationInfo	InstallationInfo	Yes	Backend credentials for the current app installation
installationInfo.installation_id	string	Yes	Installation ID matching the context's installationId
installationInfo.shared_secret	string	Yes	Base64-encoded shared secret from the installation callback
installationInfo.ones_base_url	string	Yes	ONES base URL from the installation callback for uploads and updates

Returns WikiMacroClient. The client retains a copy of installation data; recreate it when credentials change. Creation does not verify that the credentials can still authorize server requests.

client.instance

Bind the client to an existing macro context without sending a request.

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

interface BindMacro {
  (client: WikiMacroClient, context: WikiMacroContext): WikiMacroInstance
}

const bindMacro: BindMacro = (client, context) => client.instance(context)

Parameter	Type	Required	Description
context	WikiMacroContext	Yes	Macro identity, team, document and card location; see the types reference for each field

Returns WikiMacroInstance with uploadResource and saveExportSpec. Binding validates and copies context. Mutating the original object does not change the target; bind a new instance when the target changes.

Errors

Error code	Meaning and trigger	Handling
INVALID_MACRO_CONTEXT	Missing shared secret or ONES base URL; protocolVersion is not 2; installation identity differs; or team, document, card or macro identifiers are invalid.	Use stored installation data and runtime-provided context. Check ownership and required fields before binding again.

instance can throw synchronously. Include creation, binding and method calls in try / catch. Valid field formats do not prove server authorization; app availability and card ownership are checked during uploads and updates.

Example

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

async function updateSummary(
  installationInfo: InstallationInfo,
  context: WikiMacroContext,
  text: string,
) {
  try {
    const client = wiki.macro(installationInfo)
    const macro = client.instance(context)
    await macro.saveExportSpec([{ type: 'text', data: text }], [])
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error))
    throw error
  }
}