macro.saveExportSpec

Update the bound macro's static content and resource references for public sharing, mobile, search and exports.

Signature

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

interface MacroStaticAPI {
  saveExportSpec(exportSpec: WikiMacroExportSpec[], resources: string[]): Promise<void>
}

Parameters

Parameter	Type	Required	Description
exportSpec	WikiMacroExportSpec[]	Yes	Complete static text, link and image entries; at most 1000, or [] for no content
resources	string[]	Yes	Complete references to retain: document resource IDs or valid HTTPS image URLs; use [] without additional resources

The SDK merges image references and removes duplicates. The final resource set allows at most 1000 items. Combined serialized UTF-8 exportSpec and final resources must not exceed 1 MiB. Images accept document resource IDs or HTTPS URLs; links accept HTTP, HTTPS and mailto. See Macro types for fields.

This replaces complete static content instead of appending or patching it. Passing ([], []) clears static entries and resource references. Retain content and resources still required by the app.

Returns and behavior

Returns Promise<void> after the platform confirms success. It does not return context, update time or a card object.

• Does not change customData, require a configuration edit session or create a page version.
• Refresh sharing/mobile pages or export again to see successful updates. Search uses updated static text; existing exported files remain unchanged.
• Does not update app business data or automatically refresh already open pages.

Business persistence and static publication are independent. If business persistence succeeds but publication fails, retry the same static content without repeating the business write. Prevent older requests from overwriting newer business results.

Errors

Errors report through Error.message, not a uniform code field.

Error code or message	Meaning and trigger	Handling
INVALID_MACRO_CONTEXT	Installation data or bound context violates the client constraints.	Correct credentials and target context, then create a new instance.
INVALID_EXPORT_SPEC	Non-array parameters, invalid entries or fields, invalid link protocols or image references, more than 1000 entries or final resources, or combined JSON exceeding the size limit.	Correct entry formats, resource references, counts and size before submitting complete content.
INVALID_MACRO_CONFIGURATION	The ONES base URL parses as a URL but uses a protocol other than HTTP or HTTPS.	Use the callback URL. A URL that cannot be parsed can also throw a native TypeError.
CARD_UPDATE_FAILED	The API response does not contain OK; static publication cannot be confirmed.	Retain content for synchronization and inspect the response; do not report success early.
CARD_UPDATE_FAILED: AuthFailure	Invalid installation credentials, a disabled installation or failed app authentication.	Check app availability and stored credentials.
CARD_UPDATE_FAILED: PermissionDenied	The macro is not enabled or the target team does not belong to the installation organization.	Check macro availability and the installation-to-context association.
CARD_UPDATE_FAILED: InvalidParameter	Invalid request context, or Wiki rejected the card identity, static entries or resources.	Verify macro, installation, document and card association and correct static content.
CARD_UPDATE_FAILED: ServerError	The platform-to-Wiki update failed or was rejected, including a card that no longer exists.	Check card existence and service status before synchronizing again.
CARD_UPDATE_FAILED: <HTTP status>	The request failed without a usable business error code.	Inspect HTTP authentication, permissions and service status.
CARD_UPDATE_FAILED: network error	The request failed without a usable business code or HTTP status, for example after a timeout or disconnection. The update may already have been written.	Retry the same static content after recovery without repeating business writes.

These are common business codes. Other server errors are appended after CARD_UPDATE_FAILED: . The SDK exports no dedicated macro error class; do not expect Node SDK methods to return Web SDK edit-session error codes.

Example

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

async function publishResult(
  installationInfo: InstallationInfo,
  context: WikiMacroContext,
  summary: string,
  detailsUrl: string,
) {
  const exportSpec: WikiMacroExportSpec[] = [
    { type: 'text', data: summary },
    { type: 'link', data: { title: 'Details', url: detailsUrl } },
  ]
  try {
    const macro = wiki.macro(installationInfo).instance(context)
    await macro.saveExportSpec(exportSpec, [])
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error))
    throw error
  }
}

Supply a valid HTTP, HTTPS or mailto detailsUrl. For images, upload a resource first or provide a valid HTTPS image URL accessible in the target scenarios.