# Create a macro client and instance

URL: https://docs.ones.cn/developer/abilities/node-sdk/wiki-macro/client

## wiki.macro

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

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

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

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