miro-sdk-patterns

name	miro-sdk-patterns
description	Apply production-ready patterns for @mirohq/miro-api client usage. Use when implementing Miro integrations, refactoring SDK usage, or establishing coding standards for Miro REST API v2. Trigger with phrases like "miro SDK patterns", "miro best practices", "miro code patterns", "miro client wrapper", "miro typescript".
allowed-tools	Read, Write, Edit
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","miro","patterns","typescript"]
compatibility	Designed for Claude Code

Miro SDK Patterns

Overview

Production-ready patterns for the @mirohq/miro-api Node.js client and direct REST API v2 usage. Covers the high-level Miro client (stateful, OAuth-aware) and the low-level MiroApi client (stateless, token-based).

Prerequisites

• @mirohq/miro-api installed
• TypeScript 5+ project
• Understanding of Miro REST API v2 item model

Two Client Modes

import { Miro, MiroApi } from '@mirohq/miro-api';

// HIGH-LEVEL: Stateful, manages OAuth tokens per user
// Use for multi-user apps (SaaS, web apps with OAuth)
const miro = new Miro({
  clientId: process.env.MIRO_CLIENT_ID!,
  clientSecret: process.env.MIRO_CLIENT_SECRET!,
  redirectUrl: process.env.MIRO_REDIRECT_URI!,
});
const userApi = await miro.as('user-id');  // Returns MiroApi scoped to user

// LOW-LEVEL: Stateless, pass token directly
// Use for scripts, automation, single-user integrations
const api = new MiroApi(process.env.MIRO_ACCESS_TOKEN!);

Pattern 1: Type-Safe Board Service

// src/miro/board-service.ts
import { MiroApi } from '@mirohq/miro-api';


  {
  : ;
  : ;
  : ;
  : ;
  : ;
  : ;
}

  {
  : ;
  :  |  |  |  |  |  |  |  | ;
  : <, >;
  : { : ; : ; :  };
  ?: { ?: ; ?:  };
  : ;
  : { : ; :  };
}

 <T> {
  : T[];
  : ;
  : ;
  : ;
  : ;
  ?: ;
}

   {
  () {}

   (: ): <> {
     response =  ..(boardId);
     response.    ;
  }

   (
    : ,
    : { ?: ; ?: ; ?:  } = {}
  ): <<>> {
     params =  ();
     (options.) params.(, options.);
     (options.) params.(, (options.));
     (options.) params.(, options.);

     response =  (
      ,
      { : .() }
    );
     response.();
  }

   (: ): <[]> {
     : [] = [];
     :  | ;

     {
       page =  .(boardId, { : , cursor });
      items.(...page.);
      cursor = page.;
    }  (cursor);

     items;
  }

   () {
     {
      : ,
      : ,
    };
  }
}