macro.uploadResource

Upload a file as a resource of the Wiki document containing the bound macro and return its resource ID.

Signature

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

interface MacroResourceAPI {
  uploadResource(file: WikiMacroResourceFile): Promise<string>
}

Parameters

Parameter	Type	Required	Description
file	WikiMacroResourceFile	Yes	Filename and binary data, not a browser File, path or URL
file.name	string	Yes	Nonempty original filename, at most 255 UTF-8 bytes, without /, backslashes, line breaks, null characters or double quotes
file.data	Uint8Array	Yes	Binary data, including Node.js Buffer; size above zero and at most 20 MiB

Returns and behavior

Returns Promise<string> resolving to a Wiki document resource ID, not a URL or an additional original filename. Retain file.name in your app if it must be displayed later.

Uploads use installation credentials without a user login session or macro configuration edit session. The app and macro must be enabled and the target card must belong to this installation and document. Your backend must still authorize the initiating user's business operation.

Wiki document storage manages these files. Uploading does not update exportSpec, change customData or create a page version. Call saveExportSpec to display the resource in static content. Wiki file type, extension and quota checks also apply.

Errors

Errors report through Error.message, not a uniform code field. Catch the complete operation.

Error code or message	Meaning and trigger	Handling
INVALID_MACRO_CONTEXT	Installation data or bound context violates the client constraints.	Correct credentials and context, then create a new instance.
INVALID_RESOURCE	Invalid filename, data is not a Uint8Array, or the file is empty or exceeds 20 MiB.	Correct name, binary type and size instead of retrying an invalid file.
INVALID_MACRO_CONFIGURATION	The ONES base URL parses as a URL but uses a protocol other than HTTP or HTTPS.	Use the installation callback URL. A URL that cannot be parsed can also throw a native TypeError.
RESOURCE_UPLOAD_FAILED	The response does not contain OK, or the resource ID is missing, empty or invalid.	Inspect the response and do not publish an unusable ID.
RESOURCE_UPLOAD_FAILED: AuthFailure	Invalid installation credentials, a disabled installation or failed app authentication.	Check app availability and stored installation credentials.
RESOURCE_UPLOAD_FAILED: PermissionDenied	The macro is unavailable or the server denies access to the card or document resources.	Check app, macro and document ownership and availability.
RESOURCE_UPLOAD_FAILED: InvalidParameter	Server validation of the upload protocol, context, filename or digest failed.	Check parameters and pass original binary data through the SDK.
RESOURCE_UPLOAD_FAILED: ServerError	The Wiki upload failed, Wiki rejected the file or the resource response was invalid.	Check file restrictions and service logs; retry after fixing the file or recovering the service.
RESOURCE_UPLOAD_FAILED: <HTTP status>	The request failed without a usable business error code.	Inspect HTTP authentication, permissions and service status.
RESOURCE_UPLOAD_FAILED: network error	The request failed without a usable business code or HTTP status, for example after a timeout or disconnection.	Retain the file and retry after recovery. A timeout does not prove the file was not uploaded.

These are common business codes. Other server errors are appended after RESOURCE_UPLOAD_FAILED: . Do not log installation secrets or complete request configuration.

Example

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

async function publishImage(
  installationInfo: InstallationInfo,
  context: WikiMacroContext,
  filePath: string,
) {
  try {
    const macro = wiki.macro(installationInfo).instance(context)
    const data = await readFile(filePath)
    const resourceId = await macro.uploadResource({ name: 'summary.png', data })
    await macro.saveExportSpec(
      [
        { type: 'text', data: 'Latest summary' },
        { type: 'image', data: resourceId },
      ],
      [resourceId],
    )
    return resourceId
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error))
    throw error
  }
}

This replaces complete static content. Retain other required entries and resources. If uploading succeeds but static publication fails, keep the resource ID and retry only static publication.