@airsoko/partner-app

Official SDK for Airsoko partner apps on Next.js — MAPI GraphQL proxy, OAuth install, webhooks, merchant launch, embedded admin bridge, middleware, and React hooks.

Zero runtime dependencies. Optional next and react peer dependencies for route factories and hooks.

Customer OAuth (shop sign-in for storefront apps) uses @airsoko/oauth-client. Partner apps use MAPI app OAuth (/api/apps/oauth/* on MAPI).

Requirements

• Node.js 18 or later
• Next.js 13+ (App Router route handlers and middleware)
• React 17+ (hooks and providers)

Your app also needs its own session and storage stack (for example NextAuth + SQLite). Those are not bundled by this package.

Installation

npm install @airsoko/partner-app next react

For a full project scaffold with conventions, env templates, and sample pages:

npx @airsoko/cli app init my-partner-app

Partner dashboard setup

1. Create a partner app in the partner dashboard (handle, app URL, scopes).
2. Set credentials in .env.local (see Environment).
3. Register this OAuth redirect URI:

https://your-app.example.com/api/airsoko/oauth/callback

Legacy apps using legacySegments: true may use /api/oauth/callback instead.

Quick start

Like NextAuth: one catch-all API route wires every partner endpoint. Omit a handler block and that route returns 404.

// app/api/airsoko/[...slug]/route.ts
export { GET, POST } from '@/lib/partner-api'

// lib/partner-api.ts
import { createAirsokoPartnerAppRouteHandlers, partnerAppOAuthRedirectUri } from '@airsoko/partner-app'

export const { GET, POST } = createAirsokoPartnerAppRouteHandlers({
  graphql: { resolveCredentials: async (request) => ({ accessToken: '…', shopId: 1 }) },
  oauth: {
    redirectUri: partnerAppOAuthRedirectUri(),
    onSuccess: async ({ token, request }) => {
      // Persist installation in your DB, then redirect to finish login
      return new URL('/auth/complete', request.url)
    },
  },
})

Scaffolded apps from @airsoko/cli include a complete lib/partner-api.ts with SQLite + NextAuth wiring.

What the SDK handles vs your app

| SDK (@airsoko/partner-app) | Your app | |------------------------------|----------| | OAuth authorize + token exchange | Persist access_token in your database | | GraphQL / embedded proxies | Resolve credentials from session + DB | | Webhook HMAC verification | Upsert installation rows | | Merchant launch exchange | persistInstallation + one-time login codes | | Middleware CSP + install redirect | isAuthenticated (e.g. NextAuth JWT) | | React bridge + boot hooks | UI pages, product/customer panels |

Environment

AIRSOKO_* is preferred; legacy MACIVE_* from older apps still works.

# MAPI + app identity
AIRSOKO_API_BASE=https://api.airsoko.com
AIRSOKO_APP_URL=https://your-app.example.com
AIRSOKO_APP_CLIENT_ID=
AIRSOKO_APP_CLIENT_SECRET=
AIRSOKO_APP_ACCESS_TOKEN=          # optional dev bypass
AIRSOKO_APP_WEBHOOK_SECRET=
AIRSOKO_SHOP_ID=1

# Panels
NEXT_PUBLIC_AIRSOKO_ADMIN_ORIGIN=https://admin.airsoko.com
NEXT_PUBLIC_MARKETPLACE_ORIGIN=https://marketplace.airsoko.com

# NextAuth (your app)
NEXTAUTH_URL=https://your-app.example.com
NEXTAUTH_SECRET=change-me

API routes

Routes are mounted under {basePath} (default /api/airsoko).

| Path | Method | Enabled when | |------|--------|--------------| | graphql | POST | graphql omitted or configured (default on) | | oauth/start | GET | oauth block present | | oauth/callback | GET | oauth present (onSuccess required) | | standalone/exchange | POST | standalone not false (default on) | | standalone/session | POST | standalone.session configured | | embedded/context | GET | embedded not false (default on) | | embedded/credentials | POST | same | | embedded/bridge | GET | same | | session/context | GET | session block present | | webhooks/macive | POST | webhooks block present | | install/marketplace | GET | install or legacySegments: true | | install/admin | GET | same |

Disable routes explicitly:

createAirsokoPartnerAppRouteHandlers({
  oauth: false,
  webhooks: false,
  embedded: { bridge: false },
  standalone: { exchange: false },
})

Legacy paths

For existing apps on /api/macive/graphql, /api/oauth/*, /api/apps/embedded/*:

createAirsokoPartnerAppRouteHandlers({
  basePath: '/api',
  legacySegments: true,
  oauth: { onSuccess: async (...) => ... },
})

Mount at app/api/[...slug]/route.ts.

Middleware

Gate standalone routes with your session check (NextAuth example):

// middleware.ts
import type { NextRequest } from 'next/server'
import { getToken } from 'next-auth/jwt'
import {
  createAirsokoPartnerAppMiddleware,
  type PartnerAppMiddlewareRequest,
} from '@airsoko/partner-app/next'

const { middleware } = createAirsokoPartnerAppMiddleware({
  isAuthenticated: async (request: PartnerAppMiddlewareRequest) => {
    const token = await getToken({
      req: request as unknown as NextRequest,
      secret: process.env.NEXTAUTH_SECRET,
    })
    return Boolean(token?.installationId)
  },
})

export { middleware }

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
}

React

import {
  AppNavigationProvider,
  MerchantLaunchGate,
  PartnerAppProvider,
  PartnerAppBootScreen,
  useAirsokoPartnerApp,
  useAirsokoBridgeApp,
  useAppNavigation,
} from '@airsoko/partner-app/react'

Wrap your app:

<SessionProvider>
  <PartnerAppProvider>
    <MerchantLaunchGate>{children}</MerchantLaunchGate>
  </PartnerAppProvider>
</SessionProvider>

Override API paths for legacy mounts:

useAirsokoPartnerApp({
  sessionToken,
  currentPath,
  onPathChange,
  apiPaths: {
    graphql: '/api/macive/graphql',
    sessionContext: '/api/session/context',
    standaloneExchange: '/api/apps/standalone/exchange',
  },
})

Handler options

TypeScript enforces required callbacks when a block is present:

| Block | Required when present | Your responsibility | |-------|----------------------|---------------------| | oauth | onSuccess | DB upsert + redirect to /auth/complete | | session | resolveContext or resolvePayload | Read session + DB | | standalone.session | persistInstallation | DB upsert + return loginCode | | webhooks | onAppInstalled | DB upsert from webhook payload | | graphql.resolveCredentials | optional | Default uses env token; override for session/DB |

import type { AirsokoPartnerAppRouteOptions } from '@airsoko/partner-app/next'

const options: AirsokoPartnerAppRouteOptions = {
  basePath: '/api/airsoko',
  legacySegments: false,
  oauth: {
    redirectUri: 'https://app.example.com/api/airsoko/oauth/callback',
    onSuccess: async ({ token, request }) => new URL('/auth/complete', request.url),
  },
  session: {
    resolveContext: async () => ({ shopId: 1, grantedScopes: ['read_products'] }),
  },
  standalone: {
    session: {
      persistInstallation: async (input) => ({
        loginCode: 'one-time-code',
        installationId: input.installationId,
      }),
    },
  },
  webhooks: {
    onAppInstalled: async (payload) => ({ ok: true, shopId: payload.shopId }),
  },
}

Package exports

| Import | Purpose | |--------|---------| | @airsoko/partner-app | Config, MAPI, bridge, webhooks, paths, install URLs | | @airsoko/partner-app/next | Catch-all + middleware + route factories | | @airsoko/partner-app/next/middleware | Middleware only | | @airsoko/partner-app/next/graphql | GraphQL route factory | | @airsoko/partner-app/next/oauth | OAuth route factories | | @airsoko/partner-app/next/embedded | Embedded proxy routes | | @airsoko/partner-app/next/standalone | Merchant launch exchange | | @airsoko/partner-app/next/session | Session context route | | @airsoko/partner-app/react | Hooks + providers |

Embedded → standalone handoff

Embedded apps cannot use MAPI merchant_launch_token (embedded flag on the app record). To open the same shop in a full-page tab with a persistent browser session:

import { openStandaloneFromEmbedded } from '@airsoko/partner-app/react'

await openStandaloneFromEmbedded({
  sessionToken: embeddedJwt,
  shopId: context.shopId,
  appId: context.appId,
  installationId: context.installationId,
  shopName: context.shopName,
  nextPath: '/themes',
})

Flow: embedded credentials → POST /api/apps/standalone/session → new tab /auth/complete → NextAuth cookie. OAuth is only required once per browser.

Related packages

• @airsoko/cli — Scaffold partner apps and themes
• @macive/ui — Admin design system
• @airsoko/oauth-client — Customer OAuth client

License

MIT — see LICENSE.