Plugin API reference

https://api.dunea.ai/api/plugin-api/v1

curl https://api.dunea.ai/api/plugin-api/v1/app \
  -H "Authorization: Bearer $DUNEA_ACCESS_TOKEN"

curl -X POST https://api.dunea.ai/api/plugin-api/v1/token \
  -H "Authorization: Bearer $DUNEA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "installId": "6f1c2a54-3b1e-4f6e-9a55-0d5f8f0e2b11" }'

interface AccessTokenGrant {
  accessToken: string;              // dat_…
  installId: string;
  appId: string;
  grantedPermissions: Permission[];
}

import { DuneaClient, exchangeAccessToken } from '@dunea/plugin-sdk';

declare const sessionToken: string; // sent to your server by your panel

const { accessToken, installId } = await exchangeAccessToken({
  clientSecret: process.env.DUNEA_CLIENT_SECRET!,
  sessionToken, // or: installId
});
const dunea = new DuneaClient({ accessToken });

import { DuneaClient, DuneaApiError } from '@dunea/plugin-sdk';

declare const accessToken: string; // the token from plugin.installed

const dunea = new DuneaClient({ accessToken });

try {
  const [latest] = await dunea.orders.list({ limit: 1 });

  if (latest) {
    await dunea.orders.fulfil(latest.id, { trackingNumber: '1Z999AA10123456784' });
  }
} catch (error) {
  if (error instanceof DuneaApiError && error.status === 403) {
    console.warn('This install has not granted', error.missingPermission);
  }
}

interface ApiApp {
  appId: string;
  name: string;
  siteUrl: string | null;          // null until the app is published
  paymentsMode: 'test' | 'live' | 'paused';
  currency: string;
}

interface ApiProduct {
  id: string;
  slug: string;
  title: string;
  description: string | null;
  status: 'draft' | 'active' | 'archived';
  tags: string[];
  options: { name: string; values: string[] }[];
  variants: ApiVariant[];
  images: { url: string; alt: string | null }[];
}

interface ApiVariant {
  id: string;
  sku: string;
  options: string[];
  price: number;
  compareAtPrice: number | null;
  stock: number | null;            // null = stock not tracked
}

interface ProductCreate {
  title: string;
  price: number;
  description?: string;
  status?: 'draft' | 'active';
  tags?: string[];
  options?: { name: string; values: string[] }[];
  stock?: number | null;
  images?: { url: string; alt?: string }[];
}

type ProductPatch = Partial<Pick<ProductCreate, 'title' | 'description' | 'status' | 'tags'>>;

{ "set": 12 }

{ "delta": -2, "note": "Damaged in warehouse" }

interface ApiOrder {
  id: string;
  number: number;
  status: string;
  mode: 'test' | 'live';
  currency: string;
  subtotal: number;
  shipping: number;
  discount: number;
  tax: number;
  total: number;
  items: { sku: string; title: string; variantTitle: string | null; quantity: number; unitPrice: number }[];
  /** Present only with customers:read. */
  buyer?: { email: string | null; name: string | null };
  /** Present only with customers:read. */
  shippingAddress?: Record<string, unknown> | null;
  trackingNumber: string | null;
  trackingUrl: string | null;
  createdAt: string;
  paidAt: string | null;
}

interface ApiPayment {
  id: string;
  purpose: string;
  status: string;
  mode: 'test' | 'live';
  amount: number;
  refundedAmount: number;
  currency: string;
  provider: string;
  attribution: Record<string, unknown> | null;   // campaign attribution, when known
  createdAt: string | null;
}

interface ApiReview {
  id: string;
  subject: string;
  rating: number;
  title: string | null;
  body: string | null;
  authorName: string;
  verified: boolean;
  status: 'pending' | 'approved' | 'rejected';
  ownerReply: string | null;
  createdAt: string;
}

interface UsageReport {
  units: number;          // > 0, in your manifest's usage.unit
  creditsPerUnit: number; // ≤ usage.maxCreditsPerUnit
  description: string;    // on the owner's statement, ≤ 120 chars
  idempotencyKey: string; // ≤ 100 chars; a retry with the same key is charged once
}

interface ApiError {
  error: string;     // machine-readable code
  message: string;   // human-readable explanation
  /** Present on 403s: the permission the install lacks. */
  missingPermission?: Permission;
}