# Go SDK

> Go şablonunun kullandığı uygulama SDK'sı: kurulum, tipli çağrılar, imza doğrulama ve sahte platformla test.

`appsdk`, bir uygulamanın platformla konuşmak için ihtiyaç duyduğu her şeyi taşıyan Go paketidir: OAuth kurulumu, imza doğrulama, `/api/v1` için tipli bir istemci ve sözleşmelerin tipleri. Yalnızca standart kitaplığa dayanır.

Go şablonu (`biticaret app init`) SDK'nın bir kopyasını `sdk/` klasöründe getirir ve `go.mod` onu oraya bağlar:

```
require github.com/biticaret/biticaret v0.0.0-00010101000000-000000000000

replace github.com/biticaret/biticaret => ./sdk
```

```go
import "github.com/biticaret/biticaret/pkg/appsdk"
```

`sdk/` klasörünü düzenlemeyin; yeni bir şablon yeni bir kopya getirir.

Aşağıdaki örnekler şablonun `main.go` dosyasındandır veya onun yanında derlenir.

## Kurmak

Üç değer uygulamanın her yerinde kullanılır:

```go
s := &server{
	clientID:    clientID,
	adminOrigin: env("ADMIN_ORIGIN", "https://admin.biticaret.com.tr"),
	platform:    appsdk.Platform{StoreDomain: env("STORE_DOMAIN", "mybiticaret.com.tr")},
	verifier:    appsdk.Verifier{Secrets: []string{secret}},
	oauth:       appsdk.OAuth{ClientID: clientID, ClientSecret: secret, Scopes: scopes, RedirectURI: appURL + callbackPath},
	tokens:      map[int64]string{},
}
```

- `Platform`, mağazaların nerede sunulduğunu söyler. `Platform.StoreURL(store)` yalnızca gerçek bir mağaza adresi için bir URL verir; böylece gizli anahtarınız ve jetonlarınız, bir saldırganın sorguya yazdığı bir adrese gitmez.
- `Verifier`, platformun gönderdiği her şeyin imzasını denetler. `Secrets` birden çok anahtar alır; anahtar yenilerken eskisini ve yenisini birlikte verin.
- `OAuth`, kurulum akışını yürütür.

## Kurulum akışı

`application_url` işleyicisi imzalı sorguyu doğrular ve mağaza sahibini izin ekranına gönderir:

```go
store, storeID, err := s.verifier.VerifyAppURL(r.URL.Query())
if err != nil {
	http.Error(w, "Bu bağlantı platformdan gelmiyor ya da süresi doldu.", http.StatusUnauthorized)
	return
}
storeURL, err := s.platform.StoreURL(store)
if err != nil {
	http.Error(w, "Mağaza adresi geçersiz.", http.StatusBadRequest)
	return
}
```

```go
http.Redirect(w, r, s.oauth.AuthorizeURL(storeURL, state), http.StatusFound)
```

Geri dönüş işleyicisi imzayı ve `state` değerini denetler, sonra kodu jetona çevirir:

```go
q := r.URL.Query()
if err := s.verifier.VerifyQuery(q); err != nil {
	http.Error(w, "Bu bağlantı platformdan gelmiyor ya da süresi doldu.", http.StatusUnauthorized)
	return
}
```

```go
tok, err := s.oauth.Exchange(r.Context(), storeURL, q.Get("code"))
if err != nil {
	log.Printf("code exchange for %s: %v", store, err)
	http.Error(w, "Yükleme tamamlanamadı; yeniden deneyin.", http.StatusBadGateway)
	return
}
s.mu.Lock()
s.tokens[tok.StoreID] = tok.AccessToken
s.mu.Unlock()
```

Jetonu `tok.StoreID` ile saklayın. Her takas önceki jetonu iptal eder: her takastan geleni kaydedin.

## Tipli bir çağrı

`Client` bir mağazanın API'sini o kurulumun jetonuyla çağırır:

```go
func productTitles(ctx context.Context, storeURL, token string) ([]string, error) {
	c := &appsdk.Client{StoreURL: storeURL, Token: token}
	var titles []string
	pageInfo := ""
	for {
		products, next, err := c.ListProducts(ctx, pageInfo, 100)
		if err != nil {
			return nil, err
		}
		for _, p := range products {
			titles = append(titles, p.Title)
		}
		if next == "" {
			return titles, nil
		}
		pageInfo = next
	}
}
```

`storeURL`, `Platform.StoreURL` çıktısıdır. `HTTPClient` boşsa istemci 15 saniyelik zaman aşımı kullanır; yönlendirmeleri hiç izlemez.

İstemci `429` yanıtında `Retry-After` kadar bekler (en çok `MaxRateLimitWait`, 10 saniye) ve yeniden dener (en çok 3 kez; sonra `429` bir `*appsdk.APIError` olur). Platformun diğer retleri `*appsdk.APIError` olarak döner:

```go
func shopName(ctx context.Context, c *appsdk.Client) (string, error) {
	shop, err := c.GetShop(ctx)
	if appsdk.IsAPIErrorCode(err, http.StatusUnauthorized, "invalid_token") {
		// Jeton iptal edilmiş: uygulama kaldırılmış ya da yeni bir takas yapılmış.
		return "", err
	}
	if err != nil {
		return "", err
	}
	return shop.Name, nil
}
```

`appsdk.Retryable(err)`, aynı çağrının sonra başarılı olup olamayacağını söyler: `400`, `409` ve `422` kesindir, diğerleri yeniden denenebilir.

`Client` şu kaynakların yöntemlerini taşır (adresler ve izinler: [Uygulama API'si](api.md#kaynaklar)):

| Kaynak | Yöntemler |
| :--- | :--- |
| Mağaza | `GetShop` |
| Ürünler | `ListProducts`, `GetProduct`, `CreateProduct`, `UpdateProduct`, `ListProductVariants`, `ProductVariants` (250'den fazla varyantı olan bir ürünün bütün varyantları), `SetVariantCost`, `SetVariantShipping` |
| Koleksiyonlar | `ListCollections`, `GetCollection` |
| Stok | `ListLocations`, `ListInventoryLevels`, `ListInventoryHistory`, `AdjustInventoryLevel`, `MoveInventoryLevel` |
| Siparişler | `ListOrders`, `GetOrder`, `CreateRefund`, `CreateFulfillment`, `CancelFulfillment`, `CreateFulfillmentEvent`, `CaptureOrder`, `CaptureOrderAsStaff` |
| Müşteriler | `GetCustomer`, `SetCustomerTags`, `ListMarketingAudience`, `SetMarketingConsent` |
| Müşteri segmentleri | `ListCustomerSegments`, `GetCustomerSegment`, `ListSegmentCustomers` |
| İndirimler | `CreateDiscountCode`, `GetDiscountCode`, `DeleteDiscountCode` |
| Hediye kartları | `ListGiftCards`, `GetGiftCard`, `CreateGiftCard` (kartın kodu yalnızca bu yanıtta gelir), `UpdateGiftCard`, `DisableGiftCard` |
| Taslak siparişler ve kanallar | `ListDraftOrders`, `GetDraftOrder`, `CreateDraftOrder`, `UpdateDraftOrder`, `DeleteDraftOrder`, `CompleteDraftOrder`, `SendDraftInvoice`, `CreateChannelOrder` |
| Şirketler | `ListCompanies`, `GetCompany`, `CreateCompany`, `UpdateCompany`, `DeleteCompany`, `CreateCompanyLocation`, `UpdateCompanyLocation`, `DeleteCompanyLocation`, `CreateCompanyContact`, `UpdateCompanyContact`, `DeleteCompanyContact` |
| Meta alanlar | `SetMetafield`, `DeleteMetafield` |
| Meta nesneler | `ListMetaobjectDefinitions`, `GetMetaobjectDefinition`, `CreateMetaobjectDefinition`, `UpdateMetaobjectDefinition`, `DeleteMetaobjectDefinition`, `ListMetaobjects`, `GetMetaobject`, `CreateMetaobject`, `UpdateMetaobject`, `DeleteMetaobject` |
| Çeviriler | `GetTranslations`, `SetTranslations` |
| SMS | `SendSMS`, `ReportSMSStatus` |
| Web pikselleri | `GetPixelSettings`, `SetPixelSettings` |
| Faturalandırma | `ListPlans`, `CreateAppSubscription`, `GetAppSubscription`, `ListAppSubscriptions`, `ActiveAppSubscription`, `ActivePlan`, `CancelAppSubscription`, `CreateUsageRecord`, `CreateAppCredit`, `ListAppCredits` |
| Webhook teslimleri | `ListWebhookDeliveries`, `ReplayWebhookDelivery` |
| Ödeme uygulamaları | `ConfigurePaymentsApp`, `ResolvePayment`, `RejectPayment`, `PendPayment`, `ResolveFollowUp`, `RejectFollowUp` |

`pageInfo` alan listeler (`ListProducts`, `ListCollections`, `ListGiftCards`, `ListMetaobjects` gibi) bir sayfa ve sonraki sayfanın `page_info` imlecini döner; son sayfada imleç boştur.

## Webhook doğrulamak

`VerifyWebhookTopic`, tek konuya hizmet eden bir adres içindir: imzayı denetler ve imzalı konu beklenen konu değilse isteği reddeder. Şablonun bütün webhook'ları şu sarmalayıcıdan geçer:

```go
func (s *server) webhook(topic string, h func(storeID int64, body []byte) error) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		wh, err := appsdk.VerifyWebhookTopic(r, topic, s.verifier.Secrets...)
		if err != nil {
			appsdk.WriteError(w, http.StatusUnauthorized, "invalid_signature", "the signature or topic doesn't match")
			return
		}
		var head struct {
			StoreID int64 `json:"store_id"`
		}
		if json.Unmarshal(wh.Body, &head) != nil || !appsdk.ValidID(head.StoreID) {
			appsdk.WriteError(w, http.StatusBadRequest, "invalid_json", "want a JSON body with store_id")
			return
		}
		if err := h(head.StoreID, wh.Body); err != nil {
			log.Printf("webhook %s for store %d: %v", topic, head.StoreID, err)
			appsdk.WriteError(w, http.StatusInternalServerError, "internal_error", "the app couldn't handle the webhook")
			return
		}
		w.WriteHeader(http.StatusOK)
	}
}
```

```go
mux.HandleFunc("POST /webhooks/app-uninstalled", s.webhook(appsdk.TopicAppUninstalled, s.forget))
mux.HandleFunc("POST /privacy/customers-data-request", s.webhook(appsdk.TopicCustomersDataRequest, nothingKept))
```

Dönen `Webhook` değeri doğrulanmış `Body`, `Topic`, `EventID`, `StoreDomain` ve `TriggeredAt` alanlarını taşır; bu başlıkları kendiniz okumayın. Konu adları sabittir (`appsdk.TopicOrdersPaid` ve diğerleri).

## Oturum jetonunu doğrulamak

Yönetim panelindeki sayfanız sunucunuzu App Bridge'in oturum jetonuyla çağırır:

```go
tok, err := s.verifier.VerifySessionToken(appsdk.BearerToken(r), s.clientID)
if err == nil && tok.Issuer != s.adminOrigin {
	err = appsdk.ErrBadSessionToken
}
var store string
if err == nil {
	store, err = s.platform.StoreFromDest(tok.Dest)
}
if err != nil {
	appsdk.WriteError(w, http.StatusUnauthorized, "invalid_session_token", "Oturum doğrulanamadı.")
	return
}
```

`tok.StoreID` mağazanın kimliğidir; kaydınızı onunla bulun.

Sayfanın kendisi için SDK şunları verir: `appsdk.EmbeddedPage` (sayfanın hazır kabuğu, içerik güvenliği kuralıyla; `Routes` sayfayı ve yüklediği dosyaları bağlar), `appsdk.ServeAppBridge` ve `appsdk.ServeAppPage` (istemci kitaplığını ve sayfa parçalarını sunar), `appsdk.AppBridgeVersion` ve `appsdk.AppPageVersion` (bağlantıların `?v=` değerleri), `appsdk.NewStaticFiles` (`static/` klasörünü sürümlü adreslerle sunar), `appsdk.DesignSystemHead`, `appsdk.DesignSystemCSP` ve `appsdk.AppLoading` (Biticaret Design System'in `bt-*` öğeleri, onların içerik güvenliği kuralı ve yükleniyor durumu). Sayfanın nasıl kurulduğu: [Yönetim panelinde uygulama sayfası](storefront-and-admin.md#yonetim-panelinde-uygulama-sayfasi).

## Uygulama vekilini doğrulamak

```go
func (s *server) proxy(w http.ResponseWriter, r *http.Request) {
	req, err := s.verifier.VerifyProxy(r.URL.Query())
	if err != nil {
		appsdk.WriteError(w, http.StatusUnauthorized, "invalid_signature", "the proxy signature doesn't match")
		return
	}
	// req.StoreID mağaza, req.CustomerID giriş yapmış müşteridir (ziyaretçi için 0).
	fmt.Fprintf(w, "store %d, customer %d", req.StoreID, req.CustomerID)
}
```

## Sahte platformla test

`appsdktest`, bir uygulamanın testleri için sahte bir platformdur: bir mağaza için OAuth adreslerini ve `/api/v1` kaynaklarını sunar, gönderdiklerini platform gibi imzalar ve uygulamanın yaptığı çağrıları kaydeder.

Paket platformun deposundadır (`github.com/biticaret/biticaret/pkg/appsdk/appsdktest`); şablonun `sdk/` kopyası bugün onu içermez, yani bu örnek platformun deposundaki uygulamalarda derlenir.

```go
func TestProductTitles(t *testing.T) {
	p := appsdktest.New(t)
	p.Scope = appsdk.ScopeReadProducts
	p.AddProduct(appsdk.Product{ID: 101, Title: "Rehber"})

	c := &appsdk.Client{StoreURL: p.StoreURL(), Token: p.CurrentToken(), HTTPClient: &http.Client{Transport: p.Transport()}}
	products, _, err := c.ListProducts(context.Background(), "", 25)
	if err != nil {
		t.Fatal(err)
	}
	if len(products) != 1 || products[0].Title != "Rehber" {
		t.Fatalf("products = %+v", products)
	}
}
```

Uygulamanın kendisini test etmek için:

- `p.AppSDK()` uygulamaya verilecek `appsdk.Platform` değeridir; `p.Transport()` uygulamanın HTTP istemcisine verilir.
- `p.ClientID`, `p.ClientSecret` ve `p.RedirectURI` uygulamanın kimliğidir; `RedirectURI` kurulumdan önce uygulamanın OAuth dönüş adresi olmalıdır.
- `p.AppURLLink(appURL)` yönetim panelinin **Kur** ve **Aç** düğmelerinin açtığı imzalı bağlantıdır; `p.CallbackURL(state)` taze bir kodla imzalı OAuth dönüşüdür.
- `p.SendWebhook(appURL, topic, body)` uygulamaya platform gibi imzalı bir webhook gönderir; `p.SendSMSWebhook` bir SMS sağlayıcıya `sms/send` gönderir, `p.SMSes()` ve `p.SMSStatusReports()` uygulamanın istediği SMS'leri ve bildirdiği durumları verir.
- `p.SessionToken(staffID)` bir oturum jetonu imzalar.
- `p.Calls()` uygulamanın platforma yaptığı çağrıları verir.
- `p.AddCollection`, `p.AddCustomerSegment` (segmentin müşterileriyle), `p.AddGiftCard` ve `p.SetTranslationSource` uygulamanın okuyacağı koleksiyonları, segmentleri, hediye kartlarını ve çevrilecek metinleri ekler; `p.GiftCard`, `p.Metaobjects` ve `p.Translation` uygulamanın yazdıklarını verir. `$app:` ile başlayan meta nesne türleri `p.AppSlug` (boşsa `test-app`) uygulamasınındır.

Yönetim paneli sayfasının betiği için:

- `appsdktest.DrawAdminPage(t, appsdktest.AdminScript{…})` sayfanın betiğini node'da, küçük bir DOM, sahte bir App Bridge ve sayfa parçalarıyla çalıştırır ve çizdiğini döner: `Responses` uygulamanın sunucusunun JSON yanıtlarıdır, `Steps` sırayla basılacak düğmelerdir (bir düğmenin etiketi, `@primary`, `@back`, `@secondary:<etiket>`, `@next`, `@previous`). node yoksa test atlanır.
- `appsdktest.CheckDesignSystem(t, sayfa, csp)` sayfanın SDK'nın sabitlediği tasarım sistemi sürümünü bağladığını ve kaldırılmış eski sınıfları kullanmadığını denetler.
