​
Hemen SDK

Hemen Builders SDK, JavaScript/TypeScript tabanlı uygulamaların Hemen Builders API, webhook ve embedded admin app yardımcılarını tek yerden kullanması için hazırlanır. Paket workspace içinde: 
packages/SoftwareRises/HemenBuildersSdk
Varsayılan base URL: 
https://dev.hemenmagaza.com

​
Kurulum

Workspace içinden geliştirme kullanımı: 
import { HemenBuildersClient } from "./packages/SoftwareRises/HemenBuildersSdk/src/index.js";
Paket yayınlandığında hedef kullanım: 
import { HemenBuildersClient } from "@softwarerises/hemen-builders-sdk";

​
Client oluşturma

const client = new HemenBuildersClient({
  baseUrl: "https://dev.hemenmagaza.com",
  accessToken: process.env.HEMEN_BUILDERS_TOKEN,
});

​
Scope listesi

const scopes = await client.scopes.list();
Bu çağrı GET /api/builders/v1/scopes endpoint’ini kullanır.

​
OAuth helper

Client credentials token almak için: 
import { HemenBuildersClient } from "@softwarerises/hemen-builders-sdk";

const client = new HemenBuildersClient({
  baseUrl: "https://dev.hemenmagaza.com",
});

const token = await client.oauth.clientCredentials({
  clientId: process.env.HEMEN_BUILDERS_CLIENT_ID,
  clientSecret: process.env.HEMEN_BUILDERS_CLIENT_SECRET,
  scopes: ["products:read", "orders:read"],
});

​
App context kontrolü

Token aldıktan sonra hangi app ve tenant bağlamında olduğunuzu doğrulayın: 
const api = client.withToken(token.access_token);
const app = await api.apps.me();

​
Webhook signature helper

Webhook endpoint’inizde imza doğrulaması yaparken SDK helper kullanılabilir. 
import { verifyWebhookSignature } from "@softwarerises/hemen-builders-sdk";

const valid = await verifyWebhookSignature({
  eventId: request.headers["hm-event-id"],
  eventType: request.headers["hm-event-type"],
  tenantId: request.headers["hm-tenant-id"],
  rawBody,
  timestamp: request.headers["hm-timestamp"],
  signature: request.headers["hm-signature"],
  secret: process.env.HEMEN_WEBHOOK_SECRET,
});

​
Webhook helper

webhooks:write scope’u olan token ile webhook endpoint’i oluşturabilirsiniz: 
await api.webhooks.create({
  name: "ERP Orders",
  url: "https://example.com/webhooks/hemen",
  events: ["order.created"],
  max_attempts: 5,
});
Test payload üretmek için: 
const testDelivery = await api.webhooks.test(1, {
  event: "order.created",
  payload: { order_id: 123 },
});
Test endpoint dış URL’e istek atmaz; imzalı header ve body örneği üretir.

​
Storefront script helper

await client.storefrontScripts.create({
  name: "Analytics Pixel",
  script_url: "https://cdn.example.com/pixel.js",
  placement: "body_end",
  priority: 100,
  consent_required: true,
  allowed_events: ["PAGE_VIEW", "PRODUCT_VIEW"],
});
Bu işlem için app scope setinde storefront_scripts:write olmalıdır.

​
App Bridge helper

Embedded admin app içinde App Bridge, parent Hemen Mağaza admin paneliyle güvenli iletişim kurmak için kullanılır. İlk event seti: 
admin.toast
admin.redirect
admin.resize
admin.modal.close
admin.context.request
Örnek: 
import { createAppBridge } from "@softwarerises/hemen-builders-sdk";

const bridge = createAppBridge({
  allowedOrigin: "https://dev.hemenmagaza.com",
});

bridge.dispatch("admin.toast", {
  type: "success",
  message: "İşlem tamamlandı",
});

​
Modüller

ModülAmaç
clientOrtak HTTP client ve resource factory.
oauthClient credentials token helper.
webhooksSignature doğrulama ve webhook yardımcıları.
storefront-scriptsStorefront script registry helper.
app-bridgeEmbedded app postMessage client.
typesPaylaşılan sabitler ve hata tipleri.

​
Production notu

SDK, token ve secret değerlerini otomatik güvenli hale getirmez. Secret değerlerini server-side ortamda tutun; browser bundle içinde sadece App Bridge gibi client-side güvenli yardımcıları kullanın.