SDK

@getera/sdk — Era'nın her modeli ve işlemi, türleriyle; Node, Bun, Deno, edge ortamları ve tarayıcıda.

@getera/sdk, Era API'sinin türleri tanımlı istemcisidir. Her kaynak bir özelliktir (era.orders, era.leads, era.customers), her işlem onun bir yöntemidir (era.orders.cancelOrder(id)) ve her girdinin ve modelin bir TypeScript türü vardır. Hepsi API'nin sunduğu OpenAPI belgesinden üretilir; Era'ya eklenen yeni bir işlem, SDK yeniden üretildiğinde yeni bir yöntem olur. Bağımlılığı yoktur; fetch olan her yerde çalışır.

Kurulum

npm install @getera/sdk
# ya da: bun add @getera/sdk · pnpm add @getera/sdk · yarn add @getera/sdk

İstemciyi oluştur

import { createEra } from "@getera/sdk"

// Sunucuda, API anahtarıyla (Ayarlar → Gelişmiş → API anahtarları):
const era = createEra({ apiKey: process.env.ERA_API_KEY })

// …ya da OAuth ile giriş yapmış biri için (erişim token'ı ya da taze token döndüren bir fonksiyon):
const eraFor = (token: string) => createEra({ accessToken: token })
SeçenekVarsayılanNe yapar
apiKeyortamdaki ERA_API_KEYera_… anahtarı. Yalnız sunucuda.
accessToken—OAuth token'ı (erat_…) ya da () => string | Promise<string>. apiKey'den önce gelir.
baseUrlERA_BASE_URL, yoksa https://app.getera.ioBaşka bir Era adresi, ör. geliştirirken http://localhost:3001.
maxRetries2429, 5xx ve ağ hatalarında yeniden deneme — okumalarda ve tekrar önleme anahtarı taşıyan yazmalarda.
fetchgenel fetchKendi fetch'in (testler, vekil sunucular).
userAgent—Ortam izin veriyorsa gönderilir.

Nerede çalışır

Node 18+, Bun ve Deno için ek bir şey gerekmez. Anahtarı bir ortam değişkeninde tut.

import { createEra } from "@getera/sdk"
const era = createEra() // ERA_API_KEY ve ERA_BASE_URL'i okur
console.log((await era.me()).user.name)

Cloudflare Workers, Vercel Edge ve benzerleri: anahtarı platformun gizli değerlerinden ver.

import { createEra } from "@getera/sdk"

export default {
  async fetch(_req: Request, env: { ERA_API_KEY: string }) {
    const era = createEra({ apiKey: env.ERA_API_KEY })
    const { data } = await era.orders.list({ status: "unfulfilled", limit: 10 })
    return Response.json(data)
  },
}

API anahtarını asla tarayıcıya gönderme. Tarayıcıda giriş yapmış kişinin erişim token'ını kullan (kendi OAuth akışından, bkz. Kimlik doğrulama) — yalnız o kişinin yapabildiklerini yapar.

import { createEra } from "@getera/sdk"
const era = createEra({ accessToken: () => session.getFreshToken() })

Herkese açık bir mağaza vitrini için (katalog, sepet, ödeme, formlar, ziyaretçi randevuları) bunun yerine sitenin herkese açık kimliğiyle @getera/storefront kullan.

Okuma

// Bir sayfa; herhangi bir sütuna göre süzülmüş. İşleçler: [gte] [lte] [in]; null boş değerle eşleşir.
const page = await era.orders.list({ status: "unfulfilled", "created_at[gte]": "2026-10-01", order: "-created_at", limit: 50 })
page.data        // SalesOrder[]
page.next_cursor // sonraki sayfa için { cursor } olarak ver; sonda null

// Bütün satırlar, sayfa sayfa:
for await (const order of era.orders.listAll({ charge_status: "none" })) {
  console.log(order.number, order.status)
}

// Tek kayıt (yoksa ya da görme yetkin yoksa EraError 404 fırlatır):
const order = await era.orders.get("ORDER_ID")

// Yalnız bazı sütunlar ya da metin araması:
await era.customers.list({ fields: "id,name,email", q: "ada" })

Yazma

Her yazma bir işlem çalıştırır — uygulamadaki düğmenin çalıştırdığı işlemin aynısı — ve { ok, result, events } döndürür.

// Modülde düz bir oluşturma / güncelleme / silme varsa REST kısayolları:
const created = await era.customers.create({ name: "Ada Lovelace", email: "[email protected]" })
await era.customers.update("CUSTOMER_ID", { notes: "E-postayı tercih ediyor" })

// Tek kayıt üzerinde işlem: (id, girdi?)
await era.orders.cancelOrder("ORDER_ID", { reason: "Müşteri istedi" })
await era.orders.fulfilOrder("ORDER_ID", { lines: [{ orderLineId: "LINE_ID", warehouseId: "WAREHOUSE_ID", quantity: 1 }] })

// Koleksiyon üzerinde işlem: (girdi)
await era.leads.captureLead({ customerId: "CUSTOMER_ID", message: "Yıllık planla ilgileniyor" })

// Herhangi bir işlem, tam adıyla — girdisi türüyle denetlenir:
await era.actions.run("crm.capture_lead", { customerId: "CUSTOMER_ID" })

Yöntemin adı, işlemin fiilinin camelCase hâlidir (cancel_order → cancelOrder); kaynak da URL adının camelCase hâlidir (order_lines → era.orderLines). Başvuru her işlem için tam SDK çağrısını gösterir.

Girdiye bak

Her işlemin alanları başvurudaki bölümünde ve TypeScript türünde (RetailFulfilOrderInput) yazar; düzenleyicin bunları tamamlar.

Güvenle yeniden deneme

Bir yazmaya tekrar önleme anahtarı verirsen SDK onu güvenle yeniden deneyebilir; Era işi ikinci kez yapmak yerine 24 saat boyunca ilk sonucu döndürür.

await era.orders.cancelOrder("ORDER_ID", { reason: "Mükerrer" }, { idempotencyKey: crypto.randomUUID() })

Her çağrı, bir AbortController ile iptal edebilmen için { signal } da alır.

Hatalar

2xx olmayan her yanıt EraError fırlatır:

import { EraError } from "@getera/sdk"

try {
  await era.leads.captureLead({ customerId: "00000000-0000-0000-0000-000000000000" })
} catch (e) {
  if (!(e instanceof EraError)) throw e
  e.status    // 409
  e.code      // "customer_not_found" — ön koşulun kodu
  e.problems  // 422'de: [{ field, message }]
  e.requestId // destekle yazışırken bunu ver
}

code sabittir: unauthorized, invalid_token, forbidden, not_found, invalid_input, rate_limited, idempotency_in_progress, idempotency_conflict, network_error ya da işlemin kendi ön koşul kodu.

Ben kimim, neye iznim var ve hafıza

const me = await era.me()          // { user, workspace, credential: { kind, scopes }, modules: { crm: ["read","write"], … } }
const actions = await era.actions.list() // bu kimlik bilgisinin çağırabildiği her işlem; girdi şeması ve ret nedenleriyle
const { results } = await era.memory.recall("Ada geçen sefer ne istemişti?", { limit: 5 }) // yapay zekâ modülü gerekir

Türler

Her model, tablosunun PascalCase adıyla dışa aktarılır (sales_order → SalesOrder, lead → Lead), her işlem girdisi de işleminin adıyla (crm.capture_lead → CrmCaptureLeadInput); ActionName ise bütün işlem adlarının birleşimidir.

import type { SalesOrder, CrmCaptureLeadInput, ActionName } from "@getera/sdk"

Örnek: bir müşteri ve bir potansiyel müşteri

create-lead.ts
import { createEra, EraError } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })

const customer = await era.customers.create(
  { name: "Ada Lovelace", email: `ada+${Date.now()}@example.com` },
  { idempotencyKey: crypto.randomUUID() },
)
const customerId = (customer.result as { id: string }).id
const lead = await era.leads.captureLead({ customerId, message: "Yıllık planla ilgileniyor" })
console.log("lead", (lead.result as { id: string }).id, "events", lead.events.join(", "))
ERA_API_KEY=era_… bun create-lead.ts
Bu sayfa yardımcı oldu mu?