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 端点，暂无真实端点示例。