SDK

由 sdk-gen 流水線從 OpenAPI 規範自動生成的官方 SDK：零執行時依賴、ESM + CJS 雙格式、型別化錯誤、游標分頁迭代器與 SSE 串流開箱即用。回應欄位與 wire 完全一致（snake_case），無需任何轉換。

安裝

npm i @appforges/sdk
# or
bun add @appforges/sdk

快速開始

import { AppForges } from "@appforges/sdk";
import { BearerAuth } from "@appforges/sdk/runtime/auth/bearer";

const client = new AppForges({
  auth: new BearerAuth(process.env.APPFORGES_ACCESS_TOKEN!),
});

// Response fields are wire-faithful (snake_case) — payloads pass through.
const profile = await client.users.getProfile();
console.log(profile.user_id, profile.phone_number);

分頁迭代

// Cursor-paginated list methods return a Paginator:
for await (const page of client.pinpagePages.listPages(profile.user_id, { query: { pageSize: 50 } })) {
  // ...one item at a time
}
// or collect everything:
const all = await client.pinpagePages.listPages(profile.user_id).all();

錯誤處理

import { AppForgesError } from "@appforges/sdk/runtime/errors";

try {
  await client.users.getProfile();
} catch (error) {
  if (error instanceof AppForgesError) {
    console.error(error.httpStatus, error.requestId, error.retryAfterMs);
  }
}

AppForgesError 帶有 httpStatus / requestId / retryAfterMs；可搭配 reason 與 traceId 定位請求。

Python 3.11+，提供同步與非同步用戶端、嚴格 pydantic 模型、OAuth、型別化錯誤、游標分頁與 SSE。回應欄位維持 snake_case；使用 httpx 與 pydantic v2。

安裝

pip install appforges==0.59.4

同步用戶端

import os
from appforges import AppForges, BearerAuth

with AppForges(auth=BearerAuth(os.environ["APPFORGES_ACCESS_TOKEN"])) as client:
    profile = client.users.get_profile()
    print(profile.user_id)

非同步用戶端

import asyncio
import os
from appforges import AsyncAppForges, BearerAuth

async def main() -> None:
    async with AsyncAppForges(auth=BearerAuth(os.environ["APPFORGES_ACCESS_TOKEN"])) as client:
        profile = await client.users.get_profile()
        print(profile.user_id)

asyncio.run(main())

使用者資料介面需要代表使用者的 OAuth access token。測試環境設定 base_url="https://api-staging.appforges.com"；with / async with 會關閉用戶端擁有的連線。

SSE 串流回應

當 API 宣告 SSE 時，可透過同步 for 或非同步 async for 逐筆讀取事件。目前公開規格未宣告 SSE 介面，因此尚無可呼叫的端點範例。

分頁迭代

with AppForges(auth=BearerAuth(os.environ["APPFORGES_ACCESS_TOKEN"])) as client:
    profile = client.users.get_profile()
    for page in client.pinpage_pages.list_pages_all(profile.user_id, page_size=50, max_pages=10):
        print(page.page_id)

# AsyncAppForges exposes the same iterator through async for.

錯誤處理

from appforges import APIError, RateLimitExceededError

with AppForges(auth=BearerAuth(os.environ["APPFORGES_ACCESS_TOKEN"])) as client:
    try:
        client.users.get_profile()
    except RateLimitExceededError as error:
        print(error.retry_after)  # seconds
    except APIError as error:
        print(error.http_status, error.reason, error.request_id, error.trace_id)

預設最多重試 2 次，遵守 Retry-After；寫入請求僅依冪等約定重試。APIError 保留狀態碼、reason、request_id 與 trace_id。未提供的欄位不傳送；只有可空欄位接受明確的 None。

Go 1.23+，僅使用標準庫，無第三方執行時依賴。提供 context 取消、嚴格模型、OAuth、型別化錯誤、游標分頁與 SSE；JSON 欄位保留 snake_case。

安裝

go get github.com/appforges/appforges-sdk-go@v0.59.4

快速開始

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    appforges "github.com/appforges/appforges-sdk-go"
    "github.com/appforges/appforges-sdk-go/runtime"
)

func main() {
    client, err := appforges.NewClient(runtime.WithBearerToken(os.Getenv("APPFORGES_ACCESS_TOKEN")))
    if err != nil { panic(err) }
    defer client.Close()
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    profile, err := client.Users.GetProfile(ctx)
    if err != nil { panic(err) }
    fmt.Println(runtime.Value(profile.UserId))
}

使用者資料介面需要代表使用者的 OAuth access token。測試環境使用 runtime.WithBaseURL("https://api-staging.appforges.com")；Close 釋放客戶端擁有的閒置連線。

分頁迭代

for page, err := range client.PinpagePages.ListPagesAll(ctx, appforges.PinpagePagesListPagesParams{
    UserId: runtime.Value(profile.UserId),
    PageSize: runtime.Some[int64](50),
}) {
    if err != nil { return err }
    fmt.Println(runtime.Value(page.PageId))
    // break stops fetching further pages.
}

錯誤處理

import "errors"

var limited *appforges.RateLimitExceededError
var apiError *appforges.APIError
if errors.As(err, &limited) {
    fmt.Println(limited.RetryAfter)
} else if errors.As(err, &apiError) {
    fmt.Println(apiError.StatusCode, apiError.Reason, apiError.RequestID, apiError.TraceID)
}

預設最多重試 2 次，遵守 Retry-After；寫入請求按冪等約定重試。errors.As 可取得狀態碼、reason、request_id 與 trace_id。Optional[T] 使用 Some / Null 區分值、未提供和可空欄位的顯式 null。

SSE 串流回應

宣告 SSE 的 API 回傳 iter.Seq2；break 或 context 取消會關閉回應連線。目前公開規格未宣告 SSE 端點，暫無真實端點範例。