Building apps

import crypto from "node:crypto";
import express from "express";

const CLIENT_ID = process.env.SELLORCHARD_CLIENT_ID; // app_…
const CLIENT_SECRET = process.env.SELLORCHARD_CLIENT_SECRET;
const REDIRECT_URI = "https://myapp.example.com/sellorchard/callback"; // registered exactly
const app = express();

/** RFC 3986 percent-encoding (like PHP's rawurlencode). */
const encode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());

/** hmac = HMAC-SHA256(client_secret, the other query parameters sorted by key, as an RFC 3986 query string). */
function verifyHmac(query, secret) {
  const { hmac, ...params } = query;
  if (typeof hmac !== "string") return false;
  const message = Object.keys(params)
    .filter((key) => typeof params[key] === "string")
    .sort()
    .map((key) => `${encode(key)}=${encode(params[key])}`)
    .join("&");
  const expected = crypto.createHmac("sha256", secret).update(message).digest("hex");
  return hmac.length === expected.length && crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(expected));
}

// Optional: start the install from your own site with a state tied to this browser.
app.get("/sellorchard/install", (req, res) => {
  const state = crypto.randomBytes(16).toString("hex");
  res.cookie("so_state", state, { httpOnly: true, secure: true, sameSite: "lax", maxAge: 10 * 60 * 1000 });
  const params = new URLSearchParams({ state, redirect_uri: REDIRECT_URI });
  res.redirect(`https://app.sellorchard.com/install/my-app?${params}`);
});

// The merchant approved: exchange the one-time code for an access token.
app.get("/sellorchard/callback", async (req, res) => {
  if (!verifyHmac(req.query, CLIENT_SECRET)) return res.status(400).send("Invalid hmac");

  const savedState = /(?:^|;\s*)so_state=([^;]+)/.exec(req.headers.cookie ?? "")?.[1];
  if (savedState && req.query.state !== savedState) return res.status(400).send("Invalid state");

  const response = await fetch("https://api.sellorchard.com/v1/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json", Accept: "application/json" },
    body: JSON.stringify({
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code: String(req.query.code),
      redirect_uri: REDIRECT_URI,
    }),
  });
  if (!response.ok) return res.status(502).send("Token exchange failed");

  const { access_token, scope, store } = await response.json();
  // Store the token encrypted, keyed by store.id. It never expires; it stops working on uninstall.
  await saveInstallation(store.id, { accessToken: access_token, scope, name: store.name, domain: store.domain });
  res.redirect(`/welcome?store=${encodeURIComponent(store.id)}`);
});

app.listen(3000);

<?php
// callback.php — the redirect URL registered for your app.
session_start();

$clientId = getenv('SELLORCHARD_CLIENT_ID');         // app_…
$clientSecret = getenv('SELLORCHARD_CLIENT_SECRET');
$redirectUri = 'https://myapp.example.com/sellorchard/callback.php'; // registered exactly

/** hmac = HMAC-SHA256(client_secret, the other query parameters sorted by key, as an RFC 3986 query string). */
function sellorchard_verify_hmac(array $query, string $secret): bool
{
    $hmac = $query['hmac'] ?? null;
    unset($query['hmac']);
    if (!is_string($hmac) || $hmac === '') return false;

    $query = array_filter($query, 'is_scalar');
    ksort($query, SORT_STRING);
    $message = http_build_query($query, '', '&', PHP_QUERY_RFC3986);
    return hash_equals(hash_hmac('sha256', $message, $secret), $hmac);
}

if (!sellorchard_verify_hmac($_GET, $clientSecret)) {
    http_response_code(400);
    exit('Invalid hmac');
}

// If you started the install with a state (saved in the session), it must come back unchanged.
if (isset($_SESSION['so_state']) && !hash_equals($_SESSION['so_state'], (string) ($_GET['state'] ?? ''))) {
    http_response_code(400);
    exit('Invalid state');
}
unset($_SESSION['so_state']);

$ch = curl_init('https://api.sellorchard.com/v1/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Accept: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'code' => (string) $_GET['code'],
        'redirect_uri' => $redirectUri,
    ]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    http_response_code(502);
    exit('Token exchange failed');
}

$token = json_decode($body, true);
// Store the token encrypted, keyed by store id. It never expires; it stops working on uninstall.
save_installation($token['store']['id'], $token['access_token'], $token['scope'], $token['store']['domain']);

header('Location: /welcome?store=' . urlencode($token['store']['id']));

const res = await fetch("https://api.sellorchard.com/v1/products?per_page=50", {
  headers: { Authorization: `Bearer ${installation.accessToken}`, Accept: "application/json" },
});
if (res.status === 401) {
  // The merchant uninstalled the app: stop calling and clean up.
}
const { data } = await res.json();

<?php
$ch = curl_init('https://api.sellorchard.com/v1/products?per_page=50');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $installation['access_token'], 'Accept: application/json'],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 401) {
    // The merchant uninstalled the app: stop calling and clean up.
}
$products = json_decode($body, true)['data'];

import crypto from "node:crypto";

/** Returns the claims of a valid session token, or null. */
export function verifySessionToken(token, clientId, clientSecret) {
  const parts = String(token ?? "").split(".");
  if (parts.length !== 3) return null;
  const [header, payload, signature] = parts;

  const expected = crypto.createHmac("sha256", clientSecret).update(`${header}.${payload}`).digest("base64url");
  if (signature.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) return null;

  const head = JSON.parse(Buffer.from(header, "base64url").toString("utf8"));
  const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
  if (head.alg !== "HS256") return null;
  if (claims.iss !== "sellorchard" || claims.aud !== clientId) return null;
  if (typeof claims.exp !== "number" || claims.exp < Math.floor(Date.now() / 1000)) return null;
  return claims; // { iss, aud, store, user, exp }
}

// The page loaded in the admin iframe: /app?store=…&host=…&session=…
app.get("/app", (req, res) => {
  const claims = verifySessionToken(req.query.session, process.env.SELLORCHARD_CLIENT_ID, process.env.SELLORCHARD_CLIENT_SECRET);
  if (!claims || claims.store !== req.query.store) return res.status(401).send("Open this app from your SellOrchard admin.");
  // claims.store is the store, claims.user the signed-in staff member. Look up the installation by store.
  res.render("dashboard", { storeId: claims.store, userId: claims.user });
});

<?php

function sellorchard_b64url_decode(string $value): string
{
    return base64_decode(strtr($value, '-_', '+/') . str_repeat('=', (4 - strlen($value) % 4) % 4));
}

/** Returns the claims of a valid session token, or null. */
function sellorchard_verify_session_token(string $token, string $clientId, string $clientSecret): ?array
{
    $parts = explode('.', $token);
    if (count($parts) !== 3) return null;
    [$header, $payload, $signature] = $parts;

    $expected = rtrim(strtr(base64_encode(hash_hmac('sha256', "$header.$payload", $clientSecret, true)), '+/', '-_'), '=');
    if (!hash_equals($expected, $signature)) return null;

    $head = json_decode(sellorchard_b64url_decode($header), true);
    $claims = json_decode(sellorchard_b64url_decode($payload), true);
    if (($head['alg'] ?? null) !== 'HS256' || !is_array($claims)) return null;
    if (($claims['iss'] ?? null) !== 'sellorchard' || ($claims['aud'] ?? null) !== $clientId) return null;
    if (!is_int($claims['exp'] ?? null) || $claims['exp'] < time()) return null;
    return $claims; // ['iss', 'aud', 'store', 'user', 'exp']
}

$claims = sellorchard_verify_session_token((string) ($_GET['session'] ?? ''), getenv('SELLORCHARD_CLIENT_ID'), getenv('SELLORCHARD_CLIENT_SECRET'));
if ($claims === null || $claims['store'] !== ($_GET['store'] ?? null)) {
    http_response_code(401);
    exit('Open this app from your SellOrchard admin.');
}
// $claims['store'] is the store, $claims['user'] the signed-in staff member.

// Same verification as store webhooks (see the Webhooks guide), keyed with your app's client secret.
app.post("/sellorchard/webhooks", express.raw({ type: "application/json" }), async (req, res) => {
  if (!verifySignature(req.body, req.get("X-SellOrchard-Signature"), process.env.SELLORCHARD_CLIENT_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  if (event.type === "app.uninstalled") {
    await deleteInstallation(event.store_id); // the token is already revoked
  }
  res.sendStatus(200);
});

<?php
// Same verification as store webhooks (see the Webhooks guide), keyed with your app's client secret.
$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_SELLORCHARD_SIGNATURE'] ?? '';

if (!verify_sellorchard_signature($payload, $header, getenv('SELLORCHARD_CLIENT_SECRET'))) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);
if ($event['type'] === 'app.uninstalled') {
    delete_installation($event['store_id']); // the token is already revoked
}
http_response_code(200);