الحزمة في أي تطبيق Node

npm install @dukkan.one/app-sdk

create table installs (
  install_id uuid primary key,
  store_id uuid not null,
  access_token_enc text not null,
  access_expires_at timestamptz not null,
  refresh_token_enc text not null,
  refresh_expires_at timestamptz,
  scopes text[] not null default '{}',
  reconnect_required text,
  updated_at timestamptz not null default now()
);

import { buildAuthorizeUrl, generatePkce, generateState } from "@dukkan.one/app-sdk/oauth";

export async function install(request: Request): Promise<Response> {
  const pkce = await generatePkce();
  const state = generateState();
  await stash.put(state, { verifier: pkce.verifier }, { ttlSeconds: 600 }); // server-side, never in the URL
  return Response.redirect(buildAuthorizeUrl({
    clientId: env.DUKKAN_CLIENT_ID,
    redirectUri: "https://app.example.com/dukkan/callback",
    scopes: ["orders:read", "orders:write"],
    state,
    codeChallenge: pkce.challenge,
    installToken: new URL(request.url).searchParams.get("install_token"),
  }), 302);
}

import { exchangeCode, parseCallbackQuery } from "@dukkan.one/app-sdk/oauth";
import { tokensFromResponse } from "@dukkan.one/app-sdk";

export async function callback(request: Request): Promise<Response> {
  const query = parseCallbackQuery(new URL(request.url).searchParams);
  const stashed = await stash.take(query.state);
  if (!query.ok || !stashed) return new Response("state mismatch", { status: 400 });

  const response = await exchangeCode({
    credentials: { clientId: env.DUKKAN_CLIENT_ID, clientSecret: () => env.DUKKAN_CLIENT_SECRET },
    code: query.code,
    redirectUri: "https://app.example.com/dukkan/callback",
    codeVerifier: stashed.verifier,
  });
  await tokenStore.save(tokensFromResponse(response.install_id!, null, response));
  return mintSession(response.install_id!, response.store_id!);
}

import { createDukkanClient, DukkanReconnectRequiredError } from "@dukkan.one/app-sdk";

const client = createDukkanClient({
  installId,
  tokenStore,
  credentials: { clientId: env.DUKKAN_CLIENT_ID, clientSecret: () => env.DUKKAN_CLIENT_SECRET },
});

try {
  for await (const order of client.orders.iterate({ status: "placed" })) {
    await enqueue(order.id);
  }
  await client.orders.updateStatus(orderId, "approved", { idempotency: { ref: [orderId, jobId] } });
} catch (error) {
  if (error instanceof DukkanReconnectRequiredError) await markReconnect(installId);
  else throw error;
}

import { createWebhookReceiver } from "@dukkan.one/app-sdk/webhooks";

const receiver = createWebhookReceiver({
  secretsFor: async (installId) => {
    const row = await loadInstall(installId);
    return row ? { secrets: [row.webhookSecret], storeId: row.storeId } : null;
  },
  inbox: { insertIfNew: (record) => insertIgnoringDuplicates(record) },
  handlers: {
    "order.paid": async (event) => { await recordReceipt(event.data.order_id, event.data.amount_minor); },
    "app.uninstalled": async (event) => { await purge(event.installId); },
  },
});

export async function webhooks(request: Request, context: { waitUntil(p: Promise<unknown>): void }): Promise<Response> {
  const rawBody = await request.arrayBuffer();
  const { response, process } = await receiver.receive({ rawBody, headers: request.headers });
  context.waitUntil(process());
  return Response.json(response.body, { status: response.status });
}

import { syncOrders } from "@dukkan.one/app-sdk/commerce";

const result = await syncOrders(client, {
  since: await loadHighWaterMark(installId),
  onPage: async (orders) => { for (const order of orders) await upsert(order); },
});
await saveHighWaterMark(installId, result.highWaterMark);

import { DukkanConflictError, DukkanValidationError } from "@dukkan.one/app-sdk";
import { buildCreateOrderLines, exchangeRateFor } from "@dukkan.one/app-sdk/commerce";

const store = await client.store.get();
const variants = await client.products.variants(quote.lines.map((line) => line.variantId).filter(Boolean));
const rate = exchangeRateFor(store, quote.currency); // null in the pricing currency, undefined when the store has no rate
if (rate === undefined) throw new Error(`store has no rate for ${quote.currency}`);

try {
  const { data: order, replayed } = await client.orders.create({
    currency: quote.currency,
    items: buildCreateOrderLines(quote.lines, { from: store.pricing_currency.decimals, to: quote.decimals, rate }),
    discount: { amount_minor: quote.discountMinor, title: quote.discountTitle },
    shipping: { amount_minor: quote.shippingMinor, method: "delivery" },
    customer: { name: quote.customerName, phone: quote.customerPhone, email: null },
    shipping_address: { address: quote.address, province: quote.province, city: null, notes: null },
    payment_method: "cod",
    exchange_rate: rate,
    note: quote.note,
    tags: ["quote"],
    attributes: { reference: { kind: "quote", number: quote.number, url: `https://offers.example.com/quotes/${quote.number}` } },
  }, { idempotency: { ref: ["quote-accepted", quote.id] } });
  await markConverted(quote.id, order.id, replayed);
} catch (error) {
  if (error instanceof DukkanConflictError && error.code === "insufficient_stock") {
    await askToRequote(quote.id, error.insufficientLines); // [{ variant_id, requested, available }]
  } else if (error instanceof DukkanValidationError) {
    log.warn("quote rejected", { fields: error.fieldPaths, requestId: error.requestId });
  } else throw error;
}

await client.orders.update(order.id, { tags: { add: ["invoiced"] }, attributes: { invoice_id: invoice.id } }, {
  idempotency: { ref: ["invoiced", invoice.id] },
});