@tassyir/app-bridge

​

Install

npm install @tassyir/app-bridge

​

Example

import { createAppBridge, isAppBridgeError } from '@tassyir/app-bridge';

// Create it once, as early as the page loads: its first message tells the
// dashboard the page is up.
const bridge = createAppBridge();

// Each request to your server carries a NEW ID token. Never keep one: it
// lives 60 seconds and the token endpoint accepts it once.
async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
  const { token } = await bridge.idToken();
  const headers = new Headers(init.headers);
  headers.set('Authorization', `Bearer ${token}`);
  const response = await fetch(path, { ...init, headers });
  if (!response.ok) throw new Error(`${path} answered ${response.status}`);
  return (await response.json()) as T;
}

// The frame cannot see the dashboard's language, direction or theme.
bridge.on('context.changed', ({ locale, dir, theme }) => {
  document.documentElement.lang = locale;
  document.documentElement.dir = dir;
  document.documentElement.dataset['theme'] = theme;
});

await bridge.titleBar.set({ title: 'Pending orders' });
const orders = await api<{ orderNumber: string; total: string }[]>(
  '/api/pending-orders',
);
document.querySelector('#count')!.textContent = String(orders.length);

document.querySelector('#feature')!.addEventListener('click', async () => {
  try {
    const { selection } = await bridge.resource.pick({
      type: 'product',
      multiple: true,
    });
    if (selection.length === 0) return; // the merchant cancelled
    await api('/api/featured', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(selection.map((product) => product.id)),
    });
    await bridge.toast.show({
      message: `${selection.length} products featured`,
      tone: 'success',
    });
  } catch (error) {
    if (!isAppBridgeError(error)) throw error;
    // error.code is stable; error.fix says what to do about it.
    await bridge.toast.show({ message: error.message, tone: 'error' });
  }
});

import { createTassyirApp, TassyirVerificationError } from '@tassyir/app';

const tassyir = createTassyirApp({
  clientId: process.env.TASSYIR_CLIENT_ID!, // app_…
  clientSecret: process.env.TASSYIR_CLIENT_SECRET!, // tsy_cs_…
});

export async function pendingOrders(request: Request): Promise<Response> {
  const idToken =
    request.headers.get('authorization')?.replace(/^Bearer /, '') ?? '';
  try {
    // Verifies the token (signature, your client id, 60 seconds), then reuses
    // the installation's stored offline token or exchanges this ID token for one.
    const session = await tassyir.authenticate(idToken);
    const admin = tassyir.admin(session.idToken.installationId);
    const { data } = await admin.get('/orders', {
      query: { status: 'pending', limit: 50, fields: ['orderNumber', 'total'] },
    });
    return Response.json(data);
  } catch (error) {
    if (error instanceof TassyirVerificationError) {
      return new Response(null, { status: 401 });
    }
    throw error;
  }
}

​

Who is looking

​

Calls

• idToken mints a new token on every call; the SDK never caches one. Send each token to your server once.
• toast.show: tone is info (default), success or error. The dashboard signs the toast with your app’s name and shows message as text: control and bidi characters become spaces, white space is folded, and it is cut to 150 characters. More than 2,000 characters is refused.
• modal.open shows one of your pages (path, the app-path rules below) in a dashboard modal and resolves when the modal closes. title follows the toast rules and is cut to 80 characters; "" is refused, null means none. size is small, medium (default) or large. The modal’s page may call idToken, toast.show, modal.close, resource.pick and context.get only; anything else is NOT_ALLOWED_HERE.
• App paths (navigate, modal.open) are relative to admin.page and start with one /: /reviews/2?tab=sent. No scheme or host, no backslash, white space, control or bidi character, fragment, or ., .. or empty segment (percent-encoded ones too). At most 1,024 characters before the ?, 2,048 in all, and a query of at most 1,024 characters once written the way URLSearchParams writes it.
• navigate({ path }) says your app moved to another of its pages. The frame is not reloaded (show the page yourself, for example with your router); the dashboard’s address follows, as a new history entry or, with replace: true, in place.
• navigate({ dashboard }) leaves your app: home, orders, order (with id), customers, customer (with id), tracking, inventory, products (the current store’s) or apps.
• saveBar.show shows the dashboard’s save bar, busy while saving is true. Its buttons send saveBar.save and saveBar.discard. It stays until saveBar.hide, and it does not stop the merchant from leaving the page.
• titleBar.set sets your page’s title beside the app’s name; null or "" clears it.
• resource.pick opens the dashboard’s picker for product, collection or customer and resolves when the merchant closes it: selection is empty when cancelled, one item unless multiple, 50 at most. Products are { id, name, image }, collections { id, name }, customers { id, provinceCode }, plus name and phone only when the installation holds read_customer_contact. It needs read_products (products, collections) or read_customers (customers) in your manifest.

​

Events and context

const stop = bridge.on('context.changed', (context) => {});
bridge.on('saveBar.save', () => {});
bridge.on('saveBar.discard', () => {});
stop();

​

How the bridge talks to the dashboard

• Messages go to https://app.tassyir.io only, never *. A message is taken only when it comes from the page’s parent window and from that origin. Replies are matched to calls by id.
• Ready. createAppBridge() says hello at once (a context.get), which is what makes the dashboard count the page as loaded, and it repeats it with a back-off until the dashboard answers: a message posted before the dashboard listens is lost. Calls made meanwhile wait and are sent in order once it answers.
• Leaving the page. On pagehide the bridge clears the title and hides the save bar (titleBar.set({ title: null }), saveBar.hide()), so neither outlives the page that set them. It does not when the page is kept in the back/forward cache, because the whole dashboard is kept with it.
• Limits. The dashboard counts calls per installation over a sliding minute and refuses more with RATE_LIMITED. Past 240 messages a minute it drops them without answering. The bridge counts what this page sends and refuses (RATE_LIMITED, source: 'sdk') instead of posting what the dashboard would refuse or drop.

​

Errors

• code: stable; act on it, never on message;
• call: the call that failed;
• source: dashboard (the dashboard’s reply) or sdk (refused or failed before an answer);
• path: the payload field at fault, for the SDK’s own INVALID_PAYLOAD;
• message for people, and fix, one sentence saying what to do.

​

Options

const bridge = createAppBridge({
  timeoutMs: 10_000, // default timeout of each call
  dashboardOrigin: 'http://localhost:3000', // a local or staging dashboard only
});

​

Size

​

Not here yet

​

Checking against the dashboard

TASSYIR_FRONTEND_DIR=../frontend npm run crosscheck -w @tassyir/app-bridge