# Wiki macro types

URL: https://docs.ones.cn/developer/abilities/node-sdk/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](https://docs.ones.cn/developer/abilities/web-sdk/wiki-macro-types/) for full frontend context.

## InstallationInfo

Installation callback data retained on the backend.

```ts
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.

```ts
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

```ts
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

```ts
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

```ts
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](https://docs.ones.cn/developer/abilities/node-sdk/wiki-macro/client/) .

## WikiMacroInstance

```ts
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`](https://docs.ones.cn/developer/abilities/node-sdk/wiki-macro/upload-resource/) | `Promise<string>` | Resource ID, not a download URL or original filename |
| [`saveExportSpec`](https://docs.ones.cn/developer/abilities/node-sdk/wiki-macro/save-export-spec/) | `Promise<void>` | Confirms publication without returning context or update time |

## Type usage example

```ts
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)
}
```