diff --git a/.env.example b/.env.example index fe69f21..2523321 100644 --- a/.env.example +++ b/.env.example @@ -1,3 +1,3 @@ -SYNAPSE_ENV=staging +SYNAPSE_ENV=prod SYNAPSE_GATEWAY= SYNAPSE_AGENT_KEY=agt_xxx diff --git a/CHANGELOG.md b/CHANGELOG.md index e4a760d..62c33a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,9 @@ All notable public SDK changes should be recorded here. -## 0.1.0 - Public Preview +## 0.1.0 - Production -- Published staging-first Python and TypeScript SDK guidance. +- Published production-first Python and TypeScript SDK guidance. - Standardized agent runtime credentials on `SYNAPSE_AGENT_KEY`. - Documented two invocation modes: fixed-price API invoke and token-metered LLM invoke. - Added typed owner/provider SDK return objects. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e582af9..b5b5157 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,13 @@ # Contributing -Thanks for improving the SynapseNetwork SDK. This repository is public-facing, so every change should keep the developer and AI-agent onboarding path clear, staging-first, and safe. +Thanks for improving the SynapseNetwork SDK. This repository is public-facing, so every change should keep the developer and AI-agent onboarding path clear, prod-first, and safe. ## Before You Start 1. Read `llms.txt`. 2. Use `SYNAPSE_AGENT_KEY` for agent runtime examples. -3. Treat `staging` as the only public preview environment. -4. Use Arbitrum Sepolia and MockUSDC in staging docs; do not document local gateway setup as the public integration path. +3. Treat `prod` as the public default environment. +4. Use staging only for sandbox/E2E docs with Arbitrum Sepolia and MockUSDC; do not document local gateway setup as the public integration path. 5. Never commit private keys, seed phrases, real credentials, or production tokens. ## Development diff --git a/README.md b/README.md index 9a53305..54bd5a4 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ - +

@@ -28,28 +28,30 @@ SynapseNetwork lets an agent discover services, invoke them through a gateway, a 2. Create a `SynapseClient`. 3. Search, invoke, and read the receipt. -> Public Preview default: SDK examples use `staging`, backed by `https://api-staging.synapse-network.ai`. -> After production launch, replace the public examples and tests with the `prod` environment. +> Production default: SDK examples use `prod`, backed by `https://api.synapse-network.ai`. +> Staging remains available as a sandbox for gated E2E and MockUSDC testing. -## Staging Public Preview +## Production Onboarding -Today, public developer onboarding runs on staging: +Public developer onboarding now runs on production: -- Gateway: `https://api-staging.synapse-network.ai` -- App docs: [staging.synapse-network.ai/docs/sdk](https://staging.synapse-network.ai/docs/sdk) -- Chain: Arbitrum Sepolia testnet -- Asset: MockUSDC for integration testing, not production USDC +- Website: `https://www.synapse-network.ai` +- SDK docs: `https://docs.synapse-network.ai/sdks` +- Gateway API: `https://api.synapse-network.ai` +- Asset: production USDC settlement through SynapseNetwork Recommended path: -1. Connect a wallet in the staging Gateway Dashboard. +1. Connect a wallet in the Synapse Gateway Dashboard. 2. Get or issue an Agent Key and export it as `SYNAPSE_AGENT_KEY`. -3. Set `SYNAPSE_ENV=staging`. -4. Use the free first-party `svc_synapse_echo` smoke service first, or fund staging balance with MockUSDC before paid test calls. +3. Set `SYNAPSE_ENV=prod`, or omit it because `prod` is the SDK default. +4. Use the free first-party `svc_synapse_echo` smoke service first, then run paid calls with an explicitly funded account and credential budget. 5. Run one fixed-price API invoke and one token-metered LLM invoke. 6. Read the invocation receipt and verify settlement metadata. -Developers should pass staging before any future production migration. Production docs and examples stay reserved until production DNS, contracts, gateway health, and docs deployment are verified. +### Staging Sandbox + +Staging remains available for gated E2E and integration rehearsals only: `https://api-staging.synapse-network.ai` on Arbitrum Sepolia with MockUSDC test assets. Do not use staging credentials or MockUSDC examples as the public production quickstart. ## Choose Your Integration Path @@ -72,16 +74,16 @@ Do not recompute money with floating-point math. Pass discovered prices and spen | Surface | Link | Status | |---|---|---| -| SDK Hub | [staging.synapse-network.ai/docs/sdk](https://staging.synapse-network.ai/docs/sdk) | Public Preview | -| Python SDK | [staging.synapse-network.ai/docs/sdk/python](https://staging.synapse-network.ai/docs/sdk/python) | Public Preview | -| TypeScript SDK | [staging.synapse-network.ai/docs/sdk/typescript](https://staging.synapse-network.ai/docs/sdk/typescript) | Public Preview | -| Production docs | Reserved until production docs are live | Reserved | +| SDK Docs | [docs.synapse-network.ai/sdks](https://docs.synapse-network.ai/sdks) | Production | +| Website | [www.synapse-network.ai](https://www.synapse-network.ai) | Production | +| Gateway API | [api.synapse-network.ai](https://api.synapse-network.ai) | Production | ## Gateway Environments | Environment | Gateway URL | Intended use | |---|---|---| -| `staging` | `https://api-staging.synapse-network.ai` | Public preview, test assets, integration trials | +| `prod` | `https://api.synapse-network.ai` | Default production environment | +| `staging` | `https://api-staging.synapse-network.ai` | Sandbox, gated E2E, MockUSDC integration rehearsals | Resolution rules: @@ -89,7 +91,7 @@ Resolution rules: 2. Explicit `environment` 3. Python only: `SYNAPSE_GATEWAY` 4. Python only: `SYNAPSE_ENV` -5. Default: `staging` +5. Default: `prod` The SDK never probes DNS and never falls back between environments automatically. This prevents production credentials or funds from being routed to the wrong gateway. @@ -117,7 +119,7 @@ All five SDKs expose the same public capability families: agent runtime, owner w ## Examples By SDK -All runnable examples default to staging and read `SYNAPSE_AGENT_KEY`. +All runnable examples default to production and read `SYNAPSE_AGENT_KEY`. The fixed-price smoke examples first call `svc_synapse_echo`, then fall back to another free fixed-price service if echo is unavailable. | SDK | Free fixed-price smoke | LLM smoke | Full E2E | @@ -148,7 +150,7 @@ Step 2: let your agent discover and work. ```bash pip install synapse-client -export SYNAPSE_ENV=staging +export SYNAPSE_ENV=prod export SYNAPSE_AGENT_KEY=agt_xxx ``` @@ -197,7 +199,7 @@ if (!agentKey) { const client = new SynapseClient({ credential: agentKey, - environment: "staging", + environment: "prod", }); const services = await client.search("svc_synapse_echo", { @@ -260,7 +262,7 @@ from synapse_client import SynapseAuth auth = SynapseAuth.from_private_key( "0xYOUR_PRIVATE_KEY", - environment="staging", + environment="prod", ) issued = auth.issue_credential(name="agent-preview", maxCalls=100, creditLimit=5) print(issued.credential.id, issued.token) @@ -273,7 +275,7 @@ import { Wallet } from "ethers"; import { SynapseAuth } from "@synapse-network-ai/sdk"; const wallet = new Wallet(process.env.OWNER_PRIVATE_KEY!); -const auth = SynapseAuth.fromWallet(wallet, { environment: "staging" }); +const auth = SynapseAuth.fromWallet(wallet, { environment: "prod" }); const issued = await auth.issueCredential({ name: "agent-preview", maxCalls: 100, @@ -291,7 +293,7 @@ Python: ```python from synapse_client import SynapseAuth -auth = SynapseAuth.from_private_key("0xYOUR_PRIVATE_KEY", environment="staging") +auth = SynapseAuth.from_private_key("0xYOUR_PRIVATE_KEY", environment="prod") provider = auth.provider() secret = provider.issue_secret(name="weather-api") @@ -312,7 +314,7 @@ import { Wallet } from "ethers"; import { SynapseAuth } from "@synapse-network-ai/sdk"; const auth = SynapseAuth.fromWallet(new Wallet(process.env.OWNER_PRIVATE_KEY!), { - environment: "staging", + environment: "prod", }); const provider = auth.provider(); @@ -331,7 +333,7 @@ Credential handling and vulnerability reporting live in [SECURITY.md](./SECURITY ## Python Examples -The Python examples are staging-first and live under `python/examples`. +The Python examples are production-first and live under `python/examples`. ```bash cd python @@ -346,7 +348,7 @@ PYTHONPATH="$PWD" .venv/bin/python examples/llm_smoke.py PYTHONPATH="$PWD" .venv/bin/python examples/e2e.py ``` -Register a provider service on staging: +Register a provider service on production: ```bash PYTHONPATH="$PWD" .venv/bin/python examples/provider_staging_onboarding.py \ @@ -366,7 +368,7 @@ PYTHONPATH="$PWD" .venv/bin/python examples/consumer_call_provider.py \ --payload-json '{"prompt":"hello"}' ``` -Create a fresh staging wallet, issue an Agent Key, and invoke a free service: +Create a fresh production wallet, issue an Agent Key, and invoke a free service: ```bash PYTHONPATH="$PWD" .venv/bin/python examples/consumer_wallet_to_invoke.py \ diff --git a/README.zh-CN.md b/README.zh-CN.md index a2d41e8..0d1d3a0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -14,7 +14,7 @@ - +

@@ -26,28 +26,30 @@ SynapseNetwork 让 Agent 可以发现服务、通过 gateway 调用服务,并 2. 创建 `SynapseClient`。 3. 搜索服务、调用服务、读取 receipt。 -> Public Preview 默认使用 `staging`,对应 `https://api-staging.synapse-network.ai`。 -> 生产环境上线后,再把公开示例和测试统一切换到 `prod`。 +> Production 默认使用 `prod`,对应 `https://api.synapse-network.ai`。 +> staging 仍保留为 sandbox / gated E2E 环境,使用 Arbitrum Sepolia 和 MockUSDC。 -## Staging Public Preview +## Production Onboarding -当前公开开发者接入统一走 staging: +当前公开开发者接入统一走生产环境: -- Gateway:`https://api-staging.synapse-network.ai` -- App docs:[staging.synapse-network.ai/docs/sdk](https://staging.synapse-network.ai/docs/sdk) -- 链:Arbitrum Sepolia 测试网 -- 资产:MockUSDC,用于接入测试,不是生产 USDC +- 官网:`https://www.synapse-network.ai` +- SDK 文档:`https://docs.synapse-network.ai/sdks` +- Gateway API:`https://api.synapse-network.ai` +- 资产:SynapseNetwork 生产 USDC 结算 推荐路径: -1. 在 staging Gateway Dashboard 连接钱包。 +1. 在 Synapse Gateway Dashboard 连接钱包。 2. 获取或签发 Agent Key,并设置为 `SYNAPSE_AGENT_KEY`。 -3. 设置 `SYNAPSE_ENV=staging`。 -4. 先调用免费服务;如需付费测试,先准备 MockUSDC 测试余额。 +3. 设置 `SYNAPSE_ENV=prod`,或者省略该变量,因为 SDK 默认就是 `prod`。 +4. 先调用免费服务;付费调用前确认账户余额和 credential budget。 5. 跑通一次 fixed-price API invoke 和一次 token-metered LLM invoke。 6. 读取 invocation receipt,确认结算元数据。 -开发者应先在 staging 验证通过。Production docs 与示例会在生产 DNS、合约、gateway health 和 docs deployment 验证后再统一切换。 +### Staging Sandbox + +staging 只用于 sandbox、gated E2E 和集成预演:`https://api-staging.synapse-network.ai`,链是 Arbitrum Sepolia,资产是 MockUSDC。不要把 staging credential 或 MockUSDC 示例当成生产 quickstart。 ## 选择你的接入路径 @@ -70,16 +72,16 @@ SynapseNetwork 让 Agent 可以发现服务、通过 gateway 调用服务,并 | 页面 | 链接 | 状态 | |---|---|---| -| SDK Hub | [staging.synapse-network.ai/docs/sdk](https://staging.synapse-network.ai/docs/sdk) | Public Preview | -| Python SDK | [staging.synapse-network.ai/docs/sdk/python](https://staging.synapse-network.ai/docs/sdk/python) | Public Preview | -| TypeScript SDK | [staging.synapse-network.ai/docs/sdk/typescript](https://staging.synapse-network.ai/docs/sdk/typescript) | Public Preview | -| 生产文档 | 生产文档上线前预留 | Reserved | +| SDK 文档 | [docs.synapse-network.ai/sdks](https://docs.synapse-network.ai/sdks) | Production | +| 官网 | [www.synapse-network.ai](https://www.synapse-network.ai) | Production | +| Gateway API | [api.synapse-network.ai](https://api.synapse-network.ai) | Production | ## Gateway 运行环境 | 环境 | Gateway URL | 用途 | |---|---|---| -| `staging` | `https://api-staging.synapse-network.ai` | Public preview、测试资产和接入试跑 | +| `prod` | `https://api.synapse-network.ai` | 默认生产环境 | +| `staging` | `https://api-staging.synapse-network.ai` | Sandbox、gated E2E、MockUSDC 集成预演 | 解析优先级: @@ -87,7 +89,7 @@ SynapseNetwork 让 Agent 可以发现服务、通过 gateway 调用服务,并 2. 显式 `environment` 3. 仅 Python:`SYNAPSE_GATEWAY` 4. 仅 Python:`SYNAPSE_ENV` -5. 默认:`staging` +5. 默认:`prod` SDK 不会自动探测 DNS,也不会在环境之间自动 fallback。这样可以避免生产凭据或资金被错误路由到其他 gateway。 @@ -115,7 +117,7 @@ Provider 是 owner scope 下的供给侧角色,不是第二套根账户体系 ## 各 SDK 示例 -所有 runnable examples 默认使用 staging,并读取 `SYNAPSE_AGENT_KEY`。 +所有 runnable examples 默认使用生产环境,并读取 `SYNAPSE_AGENT_KEY`。 | SDK | 免费 fixed-price smoke | LLM smoke | 完整 E2E | |---|---|---|---| @@ -145,7 +147,7 @@ bash scripts/e2e/sdk_parity_e2e.sh --env staging --skip-install ```bash pip install synapse-client -export SYNAPSE_ENV=staging +export SYNAPSE_ENV=prod export SYNAPSE_AGENT_KEY=agt_xxx ``` @@ -194,7 +196,7 @@ if (!agentKey) { const client = new SynapseClient({ credential: agentKey, - environment: "staging", + environment: "prod", }); const services = await client.search("free", { @@ -257,7 +259,7 @@ from synapse_client import SynapseAuth auth = SynapseAuth.from_private_key( "0xYOUR_PRIVATE_KEY", - environment="staging", + environment="prod", ) issued = auth.issue_credential(name="agent-preview", maxCalls=100, creditLimit=5) print(issued.credential.id, issued.token) @@ -270,7 +272,7 @@ import { Wallet } from "ethers"; import { SynapseAuth } from "@synapse-network-ai/sdk"; const wallet = new Wallet(process.env.OWNER_PRIVATE_KEY!); -const auth = SynapseAuth.fromWallet(wallet, { environment: "staging" }); +const auth = SynapseAuth.fromWallet(wallet, { environment: "prod" }); const issued = await auth.issueCredential({ name: "agent-preview", maxCalls: 100, @@ -288,7 +290,7 @@ Python: ```python from synapse_client import SynapseAuth -auth = SynapseAuth.from_private_key("0xYOUR_PRIVATE_KEY", environment="staging") +auth = SynapseAuth.from_private_key("0xYOUR_PRIVATE_KEY", environment="prod") provider = auth.provider() secret = provider.issue_secret(name="weather-api") @@ -309,7 +311,7 @@ import { Wallet } from "ethers"; import { SynapseAuth } from "@synapse-network-ai/sdk"; const auth = SynapseAuth.fromWallet(new Wallet(process.env.OWNER_PRIVATE_KEY!), { - environment: "staging", + environment: "prod", }); const provider = auth.provider(); @@ -328,13 +330,13 @@ const status = await provider.getServiceStatus(service.serviceId); ## Python 示例 -Python examples 默认面向 staging,位于 `python/examples`。 +Python examples 默认面向生产环境,位于 `python/examples`。 ```bash cd /Users/cliff/workspace/agent/Synapse-Network-Sdk/python ``` -在 staging 注册 provider service: +在生产环境注册 provider service: ```bash PYTHONPATH="$PWD" .venv/bin/python examples/provider_staging_onboarding.py \ @@ -354,7 +356,7 @@ PYTHONPATH="$PWD" .venv/bin/python examples/consumer_call_provider.py \ --payload-json '{"prompt":"hello"}' ``` -创建新的 staging wallet、签发 Agent Key,并调用免费服务: +创建新的生产 wallet、签发 Agent Key,并调用免费服务: ```bash PYTHONPATH="$PWD" .venv/bin/python examples/consumer_wallet_to_invoke.py \ diff --git a/SECURITY.md b/SECURITY.md index 25fa0da..142886c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,14 +1,14 @@ # Security Policy -## Public Preview Boundary +## Production Boundary -The SDK defaults to the Synapse public preview gateway: +The SDK defaults to the Synapse production gateway: ```text -https://api-staging.synapse-network.ai +https://api.synapse-network.ai ``` -Staging is for test assets and integration trials. Production credentials, production private keys, and live-funds workflows must only be used after the official production gateway DNS and `/health` endpoint are verified. +Production credentials, production private keys, and live-funds workflows should only target the verified production gateway. Staging remains available only for sandbox/E2E rehearsals at `https://api-staging.synapse-network.ai` with Arbitrum Sepolia and MockUSDC. ## Secrets diff --git a/SUPPORT.md b/SUPPORT.md index 4f8563a..8f26730 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,15 +1,14 @@ # Support -## Public Preview Support +## Production Support -The SDK is currently documented for staging public preview: +The SDK is currently documented for production: -- Gateway: `https://api-staging.synapse-network.ai` -- App docs: `https://staging.synapse-network.ai/docs/sdk` -- Chain: Arbitrum Sepolia -- Asset: MockUSDC, not production USDC +- Website: `https://www.synapse-network.ai` +- SDK docs: `https://docs.synapse-network.ai/sdks` +- Gateway API: `https://api.synapse-network.ai` -Developers should validate integrations on staging before any future production migration. +Staging remains available only as a sandbox/E2E target: `https://api-staging.synapse-network.ai` on Arbitrum Sepolia with MockUSDC. ## Before Opening an Issue @@ -17,7 +16,7 @@ Please include: - SDK language and version. - Whether you are using fixed-price `invoke()` / `invoke` or token-metered `invoke_llm()` / `invokeLlm()`. -- Gateway environment, normally `staging`. +- Gateway environment, normally `prod`. - Request ID and idempotency key if an invocation failed. - Redacted error payloads and stack traces. diff --git a/docs/README.md b/docs/README.md index 77bf161..f7b9f00 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,15 +10,16 @@ This directory is the public documentation source for the SynapseNetwork SDK rep 4. [Quality Gates](./quality-gates.md) 5. [Agent Map](./agent-map/README.md) -## Public Preview Environment +## Production Environment -Public developer onboarding uses staging: +Public developer onboarding uses production: -- Gateway: `https://api-staging.synapse-network.ai` -- Chain: Arbitrum Sepolia testnet -- Asset: MockUSDC for integration testing, not production USDC +- Website: `https://www.synapse-network.ai` +- SDK docs: `https://docs.synapse-network.ai/sdks` +- Gateway API: `https://api.synapse-network.ai` +- Asset: production USDC settlement through SynapseNetwork -Production docs and examples will be switched after production DNS, gateway health, contracts, and docs deployment are verified. +Staging remains a sandbox for gated E2E and integration rehearsals only: `https://api-staging.synapse-network.ai` on Arbitrum Sepolia with MockUSDC. ## Contributor Notes diff --git a/docs/agent-map/README.md b/docs/agent-map/README.md index a8bbde3..c9517be 100644 --- a/docs/agent-map/README.md +++ b/docs/agent-map/README.md @@ -64,7 +64,7 @@ Domain 摘要。 | `sdk_runtime_client` | discovery, invoke, receipt, usage, runtime errors | | `sdk_owner_auth` | wallet auth, credential issue/list/status/quota, owner control plane | | `sdk_provider_lifecycle` | provider facade, provider secrets, service registration, service lifecycle, provider health | -| `sdk_environment_config` | staging defaults, future prod switch, gateway URL resolution, public preview defaults | +| `sdk_environment_config` | prod defaults, staging sandbox, gateway URL resolution, production defaults | | `sdk_public_docs` | README, integration guides, capability inventory, examples | | `sdk_ci_quality_gates` | GitHub Actions, shell CI scripts, coverage gates | | `sdk_examples_and_e2e` | examples, smoke tests, onboarding e2e plans | @@ -79,7 +79,7 @@ Update [index.json](./index.json) in the same change when: 2. A public method is added, removed, renamed, or deprecated. 3. A validation command changes. 4. A gateway endpoint contract changes. -5. The public preview environment or staging/prod guidance changes. +5. The production environment or staging/prod guidance changes. 6. Public SDK examples change credential names, money handling, or invocation mode guidance. Do not put secrets, real tokens, private deployment URLs, or one-off incident notes in this map. @@ -98,13 +98,13 @@ Describe the product as a platform where agents call APIs and make small USDC pa 产品描述应表达:Agent 通过平台调用 API,并通过区块链支持的 USDC 结算完成小额付款。 -## Public Preview Constraint +## Production Default Constraint -公开预览约束。 +生产默认约束。 -Public SDK docs should target staging on Arbitrum Sepolia with MockUSDC test assets until production docs are live. Do not present private local gateway setup as the public developer onboarding path. +Public SDK docs should target production by default: `https://www.synapse-network.ai`, `https://docs.synapse-network.ai/sdks`, and `https://api.synapse-network.ai`. Staging is only a sandbox/E2E target on Arbitrum Sepolia with MockUSDC. Do not present private local gateway setup as the public developer onboarding path. -公开 SDK 文档在 production docs 上线前应指向 staging、Arbitrum Sepolia 和 MockUSDC 测试资产。不要把私有本地 gateway 设置作为公开开发者接入路径。 +公开 SDK 文档默认指向生产环境:`https://www.synapse-network.ai`、`https://docs.synapse-network.ai/sdks` 和 `https://api.synapse-network.ai`。staging 只作为 Arbitrum Sepolia + MockUSDC 的 sandbox/E2E 目标。不要把私有本地 gateway 设置作为公开开发者接入路径。 ## Validation diff --git a/docs/agent-map/index.json b/docs/agent-map/index.json index 1a23e2a..3571421 100644 --- a/docs/agent-map/index.json +++ b/docs/agent-map/index.json @@ -60,7 +60,7 @@ "notes": [ "Canonical runtime flow is discovery/search plus one of two invoke modes: fixed-price invoke with costUsdc/cost_usdc, or token-metered LLM invoke with maxCostUsdc/max_cost_usdc.", "Public examples should use SYNAPSE_AGENT_KEY for agent runtime credentials; SYNAPSE_API_KEY is only a Python legacy fallback.", - "Public preview examples target staging on Arbitrum Sepolia with MockUSDC test assets.", + "Public examples target production by default; staging is sandbox/E2E only on Arbitrum Sepolia with MockUSDC test assets.", "Go, Java, and .NET now expose owner auth, credential, finance, provider lifecycle, and withdrawal helpers alongside the existing runtime client.", "Do not restore old quote-first gateway calls." ] @@ -127,7 +127,7 @@ "id": "sdk_environment_config", "title": "Gateway environment configuration", "use_when": [ - "staging, future prod, gateway URL, environment resolver, or public preview defaults change", + "prod defaults, staging sandbox, gateway URL, environment resolver, or production defaults change", "README or SECURITY guidance for staging/prod changes" ], "primary_files": [ @@ -159,8 +159,8 @@ "bash scripts/ci/dotnet_checks.sh" ], "notes": [ - "Default environment is staging.", - "Public docs must describe staging as Arbitrum Sepolia plus MockUSDC until production docs are live.", + "Default environment is prod.", + "Public docs must describe production as the default and staging as sandbox/E2E only on Arbitrum Sepolia plus MockUSDC.", "Do not reintroduce removed non-staging gateway presets or gateway setup docs.", "Do not reintroduce the retired gateway domain from the old .network namespace.", "Explicit gateway URL always wins over environment preset." @@ -172,7 +172,7 @@ "use_when": [ "README, integration guides, provider guides, capability inventory, or public examples change", "the product gateway docs need to stay aligned with the SDK repo", - "staging docs links or fresh-start onboarding flow changes" + "production docs links, staging sandbox links, or fresh-start onboarding flow changes" ], "primary_files": [ "README.md", @@ -201,7 +201,7 @@ "bash scripts/ci/pr_checks.sh" ], "notes": [ - "Public docs should say Public Preview unless production DNS and health checks are verified.", + "Public docs should say Production now that production DNS and health checks are verified.", "Use agt_xxx or REPLACE_ME placeholders only.", "README and gateway docs must show SYNAPSE_AGENT_KEY -> SynapseClient first, with owner auth -> JWT -> credential issuance under Advanced.", "README and gateway docs must explain fixed-price API invoke versus token-metered LLM invoke before advanced owner/provider flows.", @@ -293,7 +293,7 @@ "SYNAPSE_OWNER_PRIVATE_KEY=0x... SYNAPSE_AGENT_KEY=agt_xxx bash scripts/e2e/sdk_parity_e2e.sh --env staging --skip-install" ], "notes": [ - "Provider staging examples require a public HTTPS endpoint reachable by the staging gateway.", + "Provider examples require a public HTTPS endpoint reachable by the selected gateway.", "Public SDK examples should pass discovered money values as strings and should not use float or Number conversions in quickstarts.", "Consumer wallet-to-invoke examples default to free services unless --allow-paid is explicit.", "E2E flows may require real staging credentials; PR CI should keep e2e out of the default gate unless explicitly configured." diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 79e8344..1979793 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -1,22 +1,25 @@ # Getting Started -Use this guide to test the SDK in the staging public preview. +Use this guide to connect the SDK to production. ## Environment -Staging is the only public preview integration path: +Production is the default public integration path: -- Gateway: `https://api-staging.synapse-network.ai` -- Chain: Arbitrum Sepolia testnet -- Asset: MockUSDC for integration testing, not production USDC +- Website: `https://www.synapse-network.ai` +- SDK docs: `https://docs.synapse-network.ai/sdks` +- Gateway API: `https://api.synapse-network.ai` +- Asset: production USDC settlement through SynapseNetwork Set: ```bash -export SYNAPSE_ENV=staging +export SYNAPSE_ENV=prod export SYNAPSE_AGENT_KEY=agt_xxx ``` +Staging remains available only as a sandbox/E2E target: `https://api-staging.synapse-network.ai` on Arbitrum Sepolia with MockUSDC. + ## Choose an Integration Path | Goal | Use | diff --git a/docs/ops/SDK_Python_Staging_Development.md b/docs/ops/SDK_Python_Staging_Development.md index a3d9d45..eb4ac83 100644 --- a/docs/ops/SDK_Python_Staging_Development.md +++ b/docs/ops/SDK_Python_Staging_Development.md @@ -1,6 +1,6 @@ # SDK Python Staging Development -`python/` 是 SynapseNetwork 的官方 Python SDK 分发与联调目录。当前所有公开验证都指向 staging;生产环境上线后再统一切换到 prod。 +`python/` 是 SynapseNetwork 的官方 Python SDK 分发与联调目录。公开 quickstart 默认指向 prod;本文只记录 staging sandbox 的专项联调方式。 ## 安装 diff --git a/docs/ops/release-checklist.md b/docs/ops/release-checklist.md index be0a182..ddbce6f 100644 --- a/docs/ops/release-checklist.md +++ b/docs/ops/release-checklist.md @@ -9,12 +9,12 @@ Use this checklist for SDK releases and public documentation updates. - [ ] `.github/workflows/ci.yml` and `.github/workflows/pr-ci.yml` are current. - [ ] 更新 CHANGELOG.md with the release date and developer-visible changes. - [ ] Public examples use `SYNAPSE_AGENT_KEY`. -- [ ] Public examples use `SYNAPSE_ENV=staging` until production launch. +- [ ] Public examples use `SYNAPSE_ENV=prod` or omit the variable because prod is the SDK default. - [ ] Fixed-price examples pass string money from discovery. - [ ] Token-metered LLM examples use `invoke_llm()` / `invokeLlm()` without fixed `cost_usdc` / `costUsdc`. - [ ] Public owner/provider returns are named SDK models/interfaces, not raw maps. -## Staging Verification +## Staging Sandbox Verification - [ ] Staging gateway health is verified. - [ ] Arbitrum Sepolia and MockUSDC language is current. @@ -22,9 +22,12 @@ Use this checklist for SDK releases and public documentation updates. - [ ] One token-metered LLM staging invoke is verified when a staging LLM service is available. - [ ] Receipt lookup is verified. -## Production Switch +## Production Verification -Do not switch public examples from staging to production until production DNS, gateway health, contracts, docs deployment, and release notes are verified together. +- [ ] Production gateway health is verified at `https://api.synapse-network.ai/health`. +- [ ] Production docs are verified at `https://docs.synapse-network.ai/sdks`. +- [ ] Production website is verified at `https://www.synapse-network.ai`. +- [ ] Public examples and docs are prod-first; staging appears only as sandbox/E2E guidance. ## Publish @@ -32,5 +35,5 @@ Do not switch public examples from staging to production until production DNS, g - [ ] Dry-run each selected package through `.github/workflows/publish-sdk.yml`. - [ ] Publish each selected package through `.github/workflows/publish-sdk.yml`. - [ ] For Go, verify the subdirectory module tag uses `go/vX.Y.Z`. -- [ ] Publish the GitHub Release with package URLs, install notes, and public-preview status. +- [ ] Publish the GitHub Release with package URLs, install notes, and production status. - [ ] Do not describe SDK packages as staging/prod deployments; SDK packages only have registry channels. diff --git a/docs/ops/sdk-release-runbook.md b/docs/ops/sdk-release-runbook.md index 4ce4e31..d64a6f9 100644 --- a/docs/ops/sdk-release-runbook.md +++ b/docs/ops/sdk-release-runbook.md @@ -1,6 +1,6 @@ # SDK Package Release Runbook -- Status: Public Preview +- Status: Production - Last verified against code: 2026-05-01 This runbook covers SynapseNetwork SDK package publishing. SDKs are **published** to language registries; they are not deployed to staging or production runtime environments. @@ -12,7 +12,7 @@ This runbook covers SynapseNetwork SDK package publishing. SDKs are **published* - New trains initialize all package versions to the train version. - A single language can hotfix forward, for example train `0.1.0` with Python package `0.1.1`. - Published package versions are immutable. Do not overwrite or republish the same version; publish a higher patch version instead. -- SDK examples may default to `environment="staging"`, but package release channels are registry channels, not Gateway environments. +- SDK examples default to `environment="prod"` or omit the environment because prod is the SDK default. Package release channels are registry channels, not Gateway environments. ## Package Platforms diff --git a/docs/quality-gates.md b/docs/quality-gates.md index a2ef44d..9aa7770 100644 --- a/docs/quality-gates.md +++ b/docs/quality-gates.md @@ -10,7 +10,7 @@ This repository uses `bash scripts/ci/pr_checks.sh` as the single PR quality gat ## Required Checks -- Repo hygiene: retired gateway domains, deprecated brand wording, README language split, staging defaults, public example credential names, string money examples, removed local gateway guidance, and sensitive tracked filenames. +- Repo hygiene: retired gateway domains, deprecated brand wording, README language split, prod defaults, public example credential names, string money examples, removed local gateway guidance, and sensitive tracked filenames. - Python: Ruff format, Ruff lint, Mypy, unit tests with coverage, source size checks, Radon cyclomatic complexity, and package build. - TypeScript: Prettier, ESLint, `tsc --noEmit`, package build, unit tests, coverage, and duplicate-code scanning. - Security: Bandit for Python source and `npm audit --omit=dev --audit-level=high` for production npm dependencies. @@ -27,7 +27,7 @@ This repository uses `bash scripts/ci/pr_checks.sh` as the single PR quality gat - TypeScript global lines, branches, functions, and statements coverage must each be at least `80%`. - Duplicate code across `python/synapse_client` and `typescript/src` must stay at or below `3%` with a `50` token minimum clone size. - Public `SynapseAuth` and `SynapseProvider` methods must return named SDK models/interfaces, never raw Python `dict` or TypeScript `Record`. Internal HTTP payloads, schemas, and patch inputs may remain map-shaped. -- Public examples must use `SYNAPSE_AGENT_KEY`, staging, Arbitrum Sepolia, MockUSDC, and string money values until production docs are live. +- Public examples must use `SYNAPSE_AGENT_KEY`, production defaults, `https://api.synapse-network.ai`, and string money values. Staging may appear only as sandbox/E2E guidance with Arbitrum Sepolia and MockUSDC. ## Refactor Rules diff --git a/docs/sdk/README.md b/docs/sdk/README.md index 10b454d..ef633e4 100644 --- a/docs/sdk/README.md +++ b/docs/sdk/README.md @@ -75,15 +75,15 @@ This does not reintroduce a public local environment preset. The local target is By default the fixed-price path first selects the Synapse first-party smoke service `svc_synapse_echo`, then falls back to any free fixed-price API service. If staging has neither, set `SYNAPSE_E2E_FIXED_SERVICE_ID`, `SYNAPSE_E2E_FIXED_COST_USDC`, and `SYNAPSE_E2E_FIXED_PAYLOAD_JSON` explicitly. -## Staging Docs +## Production Docs -The productized Gateway runbook lives in staging docs: +The productized Gateway runbook lives in production docs: -1. SDK Hub: https://staging.synapse-network.ai/docs/sdk -2. Python SDK: https://staging.synapse-network.ai/docs/sdk/python -3. TypeScript SDK: https://staging.synapse-network.ai/docs/sdk/typescript +1. SDK Hub: https://docs.synapse-network.ai/sdks +2. Website: https://www.synapse-network.ai +3. Gateway API: https://api.synapse-network.ai -Production docs are reserved until production DNS, `/health`, and docs deployment are verified. +Staging remains available only as a sandbox/E2E target. ## Agent-First Onboarding Flow @@ -112,19 +112,18 @@ Provider publishing is a separate owner-authenticated flow: ## Configuration Truth -Default environment is public preview/staging: +Default environment is production: -- `staging`: `https://api-staging.synapse-network.ai` -- Chain: Arbitrum Sepolia testnet -- Asset: MockUSDC for integration testing, not production USDC - -Production launch will switch public examples and tests from `staging` to `prod`. +- `prod`: `https://api.synapse-network.ai` +- Website: `https://www.synapse-network.ai` +- SDK docs: `https://docs.synapse-network.ai/sdks` +- `staging`: `https://api-staging.synapse-network.ai`, sandbox only on Arbitrum Sepolia with MockUSDC Python: - `api_key`: explicit parameter first, then `SYNAPSE_AGENT_KEY`, then legacy `SYNAPSE_API_KEY`. - `gateway_url`: explicit parameter first, then `SYNAPSE_GATEWAY`. -- `environment`: explicit parameter first, then `SYNAPSE_ENV`, then `staging`. +- `environment`: explicit parameter first, then `SYNAPSE_ENV`, then `prod`. - `AgentWallet.connect()` no longer uses demo credential fallback; missing real credentials fail. TypeScript: diff --git a/docs/sdk/README.zh-CN.md b/docs/sdk/README.zh-CN.md index 7478079..7b4333b 100644 --- a/docs/sdk/README.zh-CN.md +++ b/docs/sdk/README.zh-CN.md @@ -75,15 +75,15 @@ bash scripts/e2e/sdk_parity_e2e.sh --env local 默认 fixed-price 路径会先选择 Synapse 第一方 smoke 服务 `svc_synapse_echo`,找不到时再 fallback 到免费的 fixed-price API 服务。如果 staging 两者都没有,需要显式设置 `SYNAPSE_E2E_FIXED_SERVICE_ID`、`SYNAPSE_E2E_FIXED_COST_USDC` 和 `SYNAPSE_E2E_FIXED_PAYLOAD_JSON`。 -## Staging 产品文档 +## Production 产品文档 -Gateway 的产品化 runbook 以 staging docs 为准: +Gateway 的产品化 runbook 以生产 docs 为准: -1. SDK Hub: https://staging.synapse-network.ai/docs/sdk -2. Python SDK: https://staging.synapse-network.ai/docs/sdk/python -3. TypeScript SDK: https://staging.synapse-network.ai/docs/sdk/typescript +1. SDK Hub: https://docs.synapse-network.ai/sdks +2. 官网: https://www.synapse-network.ai +3. Gateway API: https://api.synapse-network.ai -Production docs 先预留,等 production DNS、`/health` 和 docs deployment 验证后再作为主链路暴露。 +staging 只保留为 sandbox/E2E 目标。 ## Agent-first 接入链路 @@ -112,19 +112,18 @@ Provider publishing 是另一条 owner-authenticated flow: ## 配置真相 -默认环境是 public preview/staging: +默认环境是生产环境: -- `staging`: `https://api-staging.synapse-network.ai`,用于 public preview、测试资产和接入试跑。 -- 链:Arbitrum Sepolia 测试网。 -- 资产:MockUSDC,用于接入测试,不是生产 USDC。 - -生产环境上线后,再把公开示例和测试从 `staging` 统一切到 `prod`。 +- `prod`: `https://api.synapse-network.ai` +- 官网:`https://www.synapse-network.ai` +- SDK 文档:`https://docs.synapse-network.ai/sdks` +- `staging`: `https://api-staging.synapse-network.ai`,仅作为 Arbitrum Sepolia + MockUSDC 的 sandbox/E2E 目标。 Python: - `api_key`: 显式参数优先,其次 `SYNAPSE_AGENT_KEY`,最后是 legacy `SYNAPSE_API_KEY`。 - `gateway_url`: 显式参数优先,其次 `SYNAPSE_GATEWAY`。 -- `environment`: 显式参数优先,其次 `SYNAPSE_ENV`,最后 `staging`。 +- `environment`: 显式参数优先,其次 `SYNAPSE_ENV`,最后 `prod`。 - `AgentWallet.connect()` 不再使用 demo credential fallback;缺少真实 credential 会失败。 TypeScript: diff --git a/docs/sdk/api-parity-matrix.md b/docs/sdk/api-parity-matrix.md index 1acd726..7a79fdf 100644 --- a/docs/sdk/api-parity-matrix.md +++ b/docs/sdk/api-parity-matrix.md @@ -2,7 +2,7 @@ This matrix keeps the SDK repo aligned with the Gateway and product docs in `Synapse-Network`. Public examples should describe these SDK surfaces first; raw Gateway routes remain implementation detail unless a developer is integrating without the SDK. -Current public environment: staging on Arbitrum Sepolia with MockUSDC test assets. +Current public environment: production at `https://api.synapse-network.ai`. Staging remains a sandbox/E2E target on Arbitrum Sepolia with MockUSDC test assets. ## Agent Runtime @@ -36,6 +36,6 @@ Current public environment: staging on Arbitrum Sepolia with MockUSDC test asset ## Documentation Rules 1. Public docs should point developers to SDK methods before raw REST routes. -2. Public docs should say staging, Arbitrum Sepolia, and MockUSDC until production launch. +2. Public docs should point to production by default and mention staging only as a sandbox/E2E target. 3. Public docs must not show private local gateway setup as the public SDK onboarding path. 4. Public SDK examples should use `SYNAPSE_AGENT_KEY`, string money values, and named result objects. diff --git a/docs/sdk/capability_inventory.md b/docs/sdk/capability_inventory.md index 5a8970c..65d6dd6 100644 --- a/docs/sdk/capability_inventory.md +++ b/docs/sdk/capability_inventory.md @@ -12,7 +12,7 @@ Consumer runtime is: 4. token-metered LLM invoke through `invoke_llm()` / `invokeLlm()` with optional `max_cost_usdc` / `maxCostUsdc` 5. `GET /api/v1/agent/invocations/{id}` -Agent runtime examples use `SYNAPSE_AGENT_KEY=agt_xxx`. Python keeps `SYNAPSE_API_KEY` only as a legacy fallback. Public preview examples target staging on Arbitrum Sepolia with MockUSDC test assets. +Agent runtime examples use `SYNAPSE_AGENT_KEY=agt_xxx`. Python keeps `SYNAPSE_API_KEY` only as a legacy fallback. Public examples target production by default. Staging remains a sandbox/E2E target on Arbitrum Sepolia with MockUSDC test assets. The old quote-first flow is not a current SDK main path. Python keeps deprecated compatibility methods that raise a clear error instead of calling removed endpoints. @@ -141,7 +141,7 @@ Provider publishing is available through `auth.provider()` and existing `Synapse Supported: -1. gateway URL resolution with explicit `gatewayURL` override and `staging` default +1. gateway URL resolution with explicit `gatewayURL` override and `prod` default 2. discovery/search 3. fixed-price invoke with string `CostUSDC` 4. token-metered LLM invoke with optional string `MaxCostUSDC` @@ -157,7 +157,7 @@ Supported: Supported: -1. gateway URL resolution with explicit `gatewayUrl` override and `staging` default +1. gateway URL resolution with explicit `gatewayUrl` override and `prod` default 2. discovery/search 3. fixed-price invoke with string `costUsdc` 4. token-metered LLM invoke with optional string `maxCostUsdc` @@ -173,7 +173,7 @@ Supported: Supported: -1. gateway URL resolution with explicit `GatewayUrl` override and `staging` default +1. gateway URL resolution with explicit `GatewayUrl` override and `prod` default 2. discovery/search 3. fixed-price invoke with string `CostUsdc` 4. token-metered LLM invoke with optional string `MaxCostUsdc` diff --git a/docs/sdk/dotnet_integration.md b/docs/sdk/dotnet_integration.md index 79b6b46..ea638d3 100644 --- a/docs/sdk/dotnet_integration.md +++ b/docs/sdk/dotnet_integration.md @@ -18,7 +18,7 @@ using SynapseNetwork.Sdk; var client = new SynapseClient(new SynapseClientOptions { Credential = Environment.GetEnvironmentVariable("SYNAPSE_AGENT_KEY")!, - Environment = "staging", + Environment = "prod", }); var services = await client.SearchAsync("svc_synapse_echo", new SearchOptions { Limit = 10 }); @@ -58,7 +58,7 @@ Use owner auth only in backend or operator tooling. Agent runtime code should ke ```csharp var auth = SynapseAuth.FromPrivateKey( Environment.GetEnvironmentVariable("SYNAPSE_OWNER_PRIVATE_KEY")!, - new SynapseAuthOptions { Environment = "staging" }); + new SynapseAuthOptions { Environment = "prod" }); var token = await auth.GetTokenAsync(); var credential = await auth.IssueCredentialAsync(new CredentialOptions diff --git a/docs/sdk/go_integration.md b/docs/sdk/go_integration.md index 1fc15d2..c3b4286 100644 --- a/docs/sdk/go_integration.md +++ b/docs/sdk/go_integration.md @@ -26,7 +26,7 @@ import ( func main() { client, err := synapse.NewClient(synapse.Options{ Credential: os.Getenv("SYNAPSE_AGENT_KEY"), - Environment: "staging", + Environment: "prod", }) if err != nil { panic(err) @@ -73,7 +73,7 @@ Use owner auth only in backend or operator tooling. Agent runtime code should ke ```go auth, err := synapse.NewAuthFromPrivateKey(os.Getenv("SYNAPSE_OWNER_PRIVATE_KEY"), synapse.AuthOptions{ - Environment: "staging", + Environment: "prod", }) if err != nil { panic(err) diff --git a/docs/sdk/java_integration.md b/docs/sdk/java_integration.md index 07fe46e..e63423d 100644 --- a/docs/sdk/java_integration.md +++ b/docs/sdk/java_integration.md @@ -21,7 +21,7 @@ import ai.synapsenetwork.sdk.SynapseClient; import java.util.Map; SynapseClient client = new SynapseClient( - SynapseClient.options(System.getenv("SYNAPSE_AGENT_KEY")).environment("staging")); + SynapseClient.options(System.getenv("SYNAPSE_AGENT_KEY")).environment("prod")); var services = client.search("svc_synapse_echo", new SynapseClient.SearchOptions()); var service = services.get(0); @@ -56,7 +56,7 @@ Use owner auth only in backend or operator tooling. Agent runtime code should ke ```java SynapseAuth.Options authOptions = new SynapseAuth.Options(); -authOptions.environment = "staging"; +authOptions.environment = "prod"; SynapseAuth auth = SynapseAuth.fromPrivateKey( System.getenv("SYNAPSE_OWNER_PRIVATE_KEY"), diff --git a/docs/sdk/python_integration.md b/docs/sdk/python_integration.md index c7b063d..e51ab96 100644 --- a/docs/sdk/python_integration.md +++ b/docs/sdk/python_integration.md @@ -15,12 +15,11 @@ Consumer runtime 主链固定为: 旧的 quote-first 方法 `create_quote()`、`create_invocation()`、`invoke_service()` 已废弃,不再访问旧 endpoint。调用这些方法会直接提示改用 discovery/search + price-asserted invoke。 -Staging 产品化 runbook: +Production 产品化 runbook: -1. https://staging.synapse-network.ai/docs/sdk/python -2. SDK Hub: https://staging.synapse-network.ai/docs/sdk - -Production docs 先预留,等 production DNS、`/health` 和 docs deployment 验证后再作为主链路暴露。 +1. SDK Hub: https://docs.synapse-network.ai/sdks +2. Website: https://www.synapse-network.ai +3. Gateway API: https://api.synapse-network.ai ## 安装 @@ -48,15 +47,14 @@ python -m pip install -e ".[dev]" 1. `environment` 显式参数 2. `SYNAPSE_ENV` -3. `staging` +3. `prod` 环境 preset: -1. `staging`: `https://api-staging.synapse-network.ai` - -当前 staging 使用 Arbitrum Sepolia 测试网和 MockUSDC 测试资产。MockUSDC 只用于接入验证,不是生产 USDC。 +1. `prod`: `https://api.synapse-network.ai` +2. `staging`: `https://api-staging.synapse-network.ai`,仅用于 sandbox/E2E -生产环境上线后,公开示例和测试再统一切换到 `prod`。 +生产默认使用真实 Gateway API。staging 使用 Arbitrum Sepolia 和 MockUSDC,仅用于 sandbox/E2E。 `AgentWallet.connect()` 不再使用 `demo_key` fallback。没有真实 credential 时会失败。 @@ -73,12 +71,12 @@ Fresh setup 不应从硬编码 credential 开始。`SYNAPSE_AGENT_KEY` 是 owner 如果 owner wallet 还没有余额,可以先选择 `price_usdc == 0` 的免费服务做 smoke path;`price_usdc > 0` 的服务需要先有可用余额、credits 或足够的 credential credit limit。 -Staging 接入建议先完成: +生产接入建议先完成: -1. `SYNAPSE_ENV=staging` +1. `SYNAPSE_ENV=prod`,或省略该变量 2. `SYNAPSE_AGENT_KEY=agt_xxx` 3. 免费 fixed-price API invoke -4. MockUSDC 余额准备后的付费 fixed-price API invoke +4. 账户余额和 credential budget 准备后的付费 fixed-price API invoke 5. token-metered LLM invoke 6. receipt 查询和结算字段核对 @@ -89,7 +87,7 @@ from synapse_client import SynapseAuth auth = SynapseAuth.from_private_key( "0xYOUR_PRIVATE_KEY", - environment="staging", + environment="prod", ) jwt = auth.get_token() @@ -124,7 +122,7 @@ from synapse_client import SynapseClient client = SynapseClient( api_key=issued.token, - environment="staging", + environment="prod", ) services = client.search("market data", limit=20, tags=["finance"]) @@ -177,9 +175,9 @@ print(result.synapse.charged_usdc, result.synapse.released_usdc) 1. `free_service_smoke.py`:优先调用第一方 `svc_synapse_echo`,找不到时搜索免费 fixed-price API service、invoke、读取 receipt。 2. `llm_smoke.py`:调用 token-metered LLM,不发送 fixed-price cost。 3. `e2e.py`:完整真实 Gateway 验证并输出 JSON lines。 -4. `provider_staging_onboarding.py`:使用 `SynapseAuth` + `auth.provider()` 在 staging 注册 provider service。 +4. `provider_staging_onboarding.py`:使用 `SynapseAuth` + `auth.provider()` 注册 provider service。 5. `consumer_call_provider.py`:使用已有 `SYNAPSE_AGENT_KEY=agt_xxx` 调用 provider service。 -6. `consumer_wallet_to_invoke.py`:创建新的 staging wallet,签发 credential,再调用免费服务。 +6. `consumer_wallet_to_invoke.py`:创建新的 wallet,签发 credential,再调用免费服务。 示例命令: diff --git a/docs/sdk/python_provider_integration.md b/docs/sdk/python_provider_integration.md index 6a3dc29..baf8d56 100644 --- a/docs/sdk/python_provider_integration.md +++ b/docs/sdk/python_provider_integration.md @@ -42,7 +42,7 @@ ## 3. 最小接入代码 -完整 staging 示例脚本: +完整生产示例脚本: ```bash cd /Users/cliff/workspace/agent/Synapse-Network-Sdk/python @@ -54,14 +54,14 @@ PYTHONPATH="$PWD" .venv/bin/python examples/provider_staging_onboarding.py \ --price-usdc 0 ``` -注意:staging gateway 必须能访问 provider endpoint,所以 `--endpoint-url` 应使用公网 HTTPS URL。 +注意:Synapse gateway 必须能访问 provider endpoint,所以 `--endpoint-url` 应使用公网 HTTPS URL。 ```python from synapse_client import SynapseAuth auth = SynapseAuth.from_private_key( "0xYOUR_PROVIDER_PRIVATE_KEY", - environment="staging", + environment="prod", ) jwt = auth.get_token() diff --git a/docs/sdk/typescript_integration.md b/docs/sdk/typescript_integration.md index 4e6e57f..379bc1f 100644 --- a/docs/sdk/typescript_integration.md +++ b/docs/sdk/typescript_integration.md @@ -15,12 +15,11 @@ Consumer runtime 主链固定为: TypeScript SDK 不暴露 quote public API。当前 gateway 的正式运行时入口是单步 price-asserted invoke。 -Staging 产品化 runbook: +Production 产品化 runbook: -1. https://staging.synapse-network.ai/docs/sdk/typescript -2. SDK Hub: https://staging.synapse-network.ai/docs/sdk - -Production docs 先预留,等 production DNS、`/health` 和 docs deployment 验证后再作为主链路暴露。 +1. SDK Hub: https://docs.synapse-network.ai/sdks +2. Website: https://www.synapse-network.ai +3. Gateway API: https://api.synapse-network.ai ## 安装 @@ -42,17 +41,16 @@ TypeScript SDK 使用显式配置: ```ts const client = new SynapseClient({ credential: issued.token, - environment: "staging", + environment: "prod", }); ``` SDK 库内部不隐式读取环境变量;Node、browser、worker runtime 都由应用层决定如何传入配置。可用环境 preset: -1. `staging`: `https://api-staging.synapse-network.ai` - -当前 staging 使用 Arbitrum Sepolia 测试网和 MockUSDC 测试资产。MockUSDC 只用于接入验证,不是生产 USDC。 +1. `prod`: `https://api.synapse-network.ai` +2. `staging`: `https://api-staging.synapse-network.ai`,仅用于 sandbox/E2E -生产环境上线后,公开示例和测试再统一切换到 `prod`。 +生产默认使用真实 Gateway API。staging 使用 Arbitrum Sepolia 和 MockUSDC,仅用于 sandbox/E2E。 显式 `gatewayUrl` 会覆盖 `environment`。 @@ -76,12 +74,12 @@ Fresh setup 不应从 `credential: "agt_xxx"` 开始。agent credential 必须 如果 owner wallet 还没有余额,可以先选择 `price_usdc == 0` 的免费服务做 smoke path;`price_usdc > 0` 的服务需要先有可用余额、credits 或足够的 credential credit limit。 -Staging 接入建议先完成: +生产接入建议先完成: -1. `SYNAPSE_ENV=staging` +1. `SYNAPSE_ENV=prod`,或省略该变量 2. `SYNAPSE_AGENT_KEY=agt_xxx` 3. 免费 fixed-price API invoke -4. MockUSDC 余额准备后的付费 fixed-price API invoke +4. 账户余额和 credential budget 准备后的付费 fixed-price API invoke 5. token-metered LLM invoke 6. receipt 查询和结算字段核对 @@ -93,7 +91,7 @@ import { SynapseAuth } from "@synapse-network-ai/sdk"; const wallet = new Wallet(process.env.OWNER_PRIVATE_KEY!); const auth = SynapseAuth.fromWallet(wallet, { - environment: "staging", + environment: "prod", }); const jwt = await auth.getToken(); @@ -151,7 +149,7 @@ import { SynapseClient } from "@synapse-network-ai/sdk"; const client = new SynapseClient({ credential: issued.token, - environment: "staging", + environment: "prod", }); const services = await client.search("market data", { diff --git a/docs/sdk/typescript_provider_integration.md b/docs/sdk/typescript_provider_integration.md index 155e186..87dfcbc 100644 --- a/docs/sdk/typescript_provider_integration.md +++ b/docs/sdk/typescript_provider_integration.md @@ -49,7 +49,7 @@ import { SynapseAuth } from "@synapse-network-ai/sdk"; const wallet = new Wallet(process.env.PROVIDER_PRIVATE_KEY!); const auth = SynapseAuth.fromWallet(wallet, { - environment: "staging", + environment: "prod", }); const jwt = await auth.getToken(); diff --git a/dotnet/src/SynapseNetwork.Sdk/SynapseClient.cs b/dotnet/src/SynapseNetwork.Sdk/SynapseClient.cs index d153cc1..a1440c7 100644 --- a/dotnet/src/SynapseNetwork.Sdk/SynapseClient.cs +++ b/dotnet/src/SynapseNetwork.Sdk/SynapseClient.cs @@ -8,7 +8,7 @@ namespace SynapseNetwork.Sdk; public sealed class SynapseClient { - public const string DefaultEnvironment = "staging"; + public const string DefaultEnvironment = "prod"; public const string StagingGatewayUrl = "https://api-staging.synapse-network.ai"; public const string ProdGatewayUrl = "https://api.synapse-network.ai"; diff --git a/dotnet/tests/SynapseNetwork.Sdk.Tests/SynapseClientTests.cs b/dotnet/tests/SynapseNetwork.Sdk.Tests/SynapseClientTests.cs index 5c95521..81b44a3 100644 --- a/dotnet/tests/SynapseNetwork.Sdk.Tests/SynapseClientTests.cs +++ b/dotnet/tests/SynapseNetwork.Sdk.Tests/SynapseClientTests.cs @@ -8,10 +8,10 @@ namespace SynapseNetwork.Sdk.Tests; public sealed class SynapseClientTests { [Fact] - public void ResolvesGatewayUrlWithStagingDefaultAndExplicitOverride() + public void ResolvesGatewayUrlWithProdDefaultAndExplicitOverride() { Assert.Equal("https://gateway.example.com", SynapseClient.ResolveGatewayUrl(gatewayUrl: "https://gateway.example.com/")); - Assert.Equal(SynapseClient.StagingGatewayUrl, SynapseClient.ResolveGatewayUrl()); + Assert.Equal(SynapseClient.ProdGatewayUrl, SynapseClient.ResolveGatewayUrl()); Assert.Throws(() => SynapseClient.ResolveGatewayUrl(environment: "local")); } diff --git a/go/synapse/client.go b/go/synapse/client.go index 6e23c3f..95da95d 100644 --- a/go/synapse/client.go +++ b/go/synapse/client.go @@ -14,7 +14,7 @@ import ( ) const ( - DefaultEnvironment = "staging" + DefaultEnvironment = "prod" StagingGatewayURL = "https://api-staging.synapse-network.ai" ProdGatewayURL = "https://api.synapse-network.ai" ) diff --git a/go/synapse/client_test.go b/go/synapse/client_test.go index 9e238d4..2ca10a8 100644 --- a/go/synapse/client_test.go +++ b/go/synapse/client_test.go @@ -17,8 +17,8 @@ func TestResolveGatewayURL(t *testing.T) { t.Fatalf("explicit gateway url should win, got=%q err=%v", got, err) } got, err = ResolveGatewayURL("", "") - if err != nil || got != StagingGatewayURL { - t.Fatalf("default environment should be staging, got=%q err=%v", got, err) + if err != nil || got != ProdGatewayURL { + t.Fatalf("default environment should be prod, got=%q err=%v", got, err) } if _, err = ResolveGatewayURL("local", ""); err == nil { t.Fatal("unsupported environment should fail") diff --git a/java/src/main/java/ai/synapsenetwork/sdk/SynapseClient.java b/java/src/main/java/ai/synapsenetwork/sdk/SynapseClient.java index 9081fe8..33a9d1d 100644 --- a/java/src/main/java/ai/synapsenetwork/sdk/SynapseClient.java +++ b/java/src/main/java/ai/synapsenetwork/sdk/SynapseClient.java @@ -20,7 +20,7 @@ import java.util.UUID; public final class SynapseClient { - public static final String DEFAULT_ENVIRONMENT = "staging"; + public static final String DEFAULT_ENVIRONMENT = "prod"; public static final String STAGING_GATEWAY_URL = "https://api-staging.synapse-network.ai"; public static final String PROD_GATEWAY_URL = "https://api.synapse-network.ai"; diff --git a/java/src/test/java/ai/synapsenetwork/sdk/SynapseClientTest.java b/java/src/test/java/ai/synapsenetwork/sdk/SynapseClientTest.java index ca68038..b6ab254 100644 --- a/java/src/test/java/ai/synapsenetwork/sdk/SynapseClientTest.java +++ b/java/src/test/java/ai/synapsenetwork/sdk/SynapseClientTest.java @@ -15,11 +15,11 @@ final class SynapseClientTest { @Test - void resolvesGatewayUrlWithStagingDefaultAndExplicitOverride() { + void resolvesGatewayUrlWithProdDefaultAndExplicitOverride() { assertEquals( "https://gateway.example.com", SynapseClient.resolveGatewayUrl("staging", "https://gateway.example.com/")); - assertEquals(SynapseClient.STAGING_GATEWAY_URL, SynapseClient.resolveGatewayUrl(null, null)); + assertEquals(SynapseClient.PROD_GATEWAY_URL, SynapseClient.resolveGatewayUrl(null, null)); assertThrows(IllegalArgumentException.class, () -> SynapseClient.resolveGatewayUrl("local", null)); } diff --git a/llm-instructions.md b/llm-instructions.md index f37d82a..746024a 100644 --- a/llm-instructions.md +++ b/llm-instructions.md @@ -17,8 +17,9 @@ CRITICAL RULES FOR AI AGENTS: 9. ALWAYS fetch and read the receipt after invocation to verify settlement. 10. IF the user asks to publish/register/manage a provider API, initialize `SynapseAuth` and use `auth.provider()`. 11. Provider setup is owner-scoped. Do not treat Provider as a separate root account. -12. PUBLIC SDK EXAMPLES MUST TARGET STAGING: `SYNAPSE_ENV=staging`, Arbitrum Sepolia, and MockUSDC test assets. +12. PUBLIC SDK EXAMPLES MUST TARGET PRODUCTION: `SYNAPSE_ENV=prod` or omit it because prod is the default, with Gateway API `https://api.synapse-network.ai`. 13. DO NOT generate private local gateway onboarding instructions for public SDK users. +14. Mention staging only as a sandbox/E2E target: `https://api-staging.synapse-network.ai` on Arbitrum Sepolia with MockUSDC. @@ -34,8 +35,9 @@ AI Agent 中文规则: 9. 调用后必须读取 receipt,确认结算状态。 10. 如果用户要求发布、注册或管理 provider API,才初始化 `SynapseAuth` 并使用 `auth.provider()`。 11. Provider 是 owner scope 下的角色,不是第二套根账户体系。 -12. 公开 SDK 示例必须指向 staging:`SYNAPSE_ENV=staging`、Arbitrum Sepolia 和 MockUSDC 测试资产。 +12. 公开 SDK 示例必须指向生产环境:`SYNAPSE_ENV=prod`,或省略该变量,因为 prod 是默认环境;Gateway API 是 `https://api.synapse-network.ai`。 13. 不要为公开 SDK 用户生成私有本地 gateway 接入说明。 +14. staging 只能作为 sandbox/E2E 目标出现:`https://api-staging.synapse-network.ai`,Arbitrum Sepolia 和 MockUSDC。 Additional runtime preferences: @@ -57,7 +59,7 @@ import os from synapse_client import SynapseClient -client = SynapseClient(api_key=os.environ["SYNAPSE_AGENT_KEY"], environment="staging") +client = SynapseClient(api_key=os.environ["SYNAPSE_AGENT_KEY"], environment="prod") services = client.search("free", limit=10) service = services[0] result = client.invoke( @@ -79,7 +81,7 @@ import { SynapseClient } from "@synapse-network-ai/sdk"; const agentKey = process.env.SYNAPSE_AGENT_KEY; if (!agentKey) throw new Error("SYNAPSE_AGENT_KEY is required"); -const client = new SynapseClient({ credential: agentKey, environment: "staging" }); +const client = new SynapseClient({ credential: agentKey, environment: "prod" }); const services = await client.search("free", { limit: 10 }); const service = services[0]; const result = await client.invoke( @@ -119,7 +121,7 @@ Provider 发布模式: ```python from synapse_client import SynapseAuth -auth = SynapseAuth.from_private_key("0xOWNER_PRIVATE_KEY", environment="staging") +auth = SynapseAuth.from_private_key("0xOWNER_PRIVATE_KEY", environment="prod") provider = auth.provider() service = provider.register_service( service_name="Weather API", @@ -132,7 +134,7 @@ service = provider.register_service( ```ts import { SynapseAuth } from "@synapse-network-ai/sdk"; -const auth = SynapseAuth.fromWallet(wallet, { environment: "staging" }); +const auth = SynapseAuth.fromWallet(wallet, { environment: "prod" }); const provider = auth.provider(); const service = await provider.registerService({ serviceName: "Weather API", diff --git a/llms.txt b/llms.txt index 4b032ca..a347512 100644 --- a/llms.txt +++ b/llms.txt @@ -8,21 +8,23 @@ This repository contains the official SynapseNetwork SDKs for TypeScript, Python - **Agent Key (`agt_xxx`)**: Runtime credential used by consumer agents to invoke services and pay. - **Service ID**: Unique identifier for a provider API. -- **Staging URL**: `https://api-staging.synapse-network.ai`; staging is the default development environment. -- **Staging Chain**: Arbitrum Sepolia testnet with MockUSDC. MockUSDC is for integration testing only and is not production USDC. +- **Production URL**: `https://api.synapse-network.ai`; prod is the default SDK environment. +- **Website**: `https://www.synapse-network.ai`. +- **SDK Docs**: `https://docs.synapse-network.ai/sdks`. +- **Staging Sandbox**: `https://api-staging.synapse-network.ai` on Arbitrum Sepolia with MockUSDC for gated E2E and integration rehearsals only. - **Money Rule**: Never recompute prices with floating-point math. Pass discovered prices and spend limits through exactly; use string amounts, for example `"0.05"`. -## Staging Public Preview +## Production Default -Use staging for every public developer example until production launch. A correct staging integration has: +Use production for public developer examples. A correct production integration has: -1. `SYNAPSE_ENV=staging` +1. `SYNAPSE_ENV=prod` or no `SYNAPSE_ENV`, because prod is the SDK default 2. `SYNAPSE_AGENT_KEY=agt_xxx` 3. Fixed-price API invoke with string `cost_usdc` / `costUsdc` from discovery 4. Token-metered LLM invoke with optional string `max_cost_usdc` / `maxCostUsdc` 5. Receipt verification after invocation -Do not generate private local gateway setup instructions for public SDK users. +Do not generate private local gateway setup instructions for public SDK users. Mention staging only as a sandbox/E2E target, not as the default quickstart path. ## Easiest Way: MCP Server @@ -57,7 +59,7 @@ if (!agentKey) { const client = new SynapseClient({ credential: agentKey, - environment: "staging", + environment: "prod", }); // Fixed-price API invoke. costUsdc must match the discovered price. @@ -96,7 +98,7 @@ agent_key = os.environ["SYNAPSE_AGENT_KEY"] client = SynapseClient( api_key=agent_key, - environment="staging", + environment="prod", ) # Fixed-price API invoke. cost_usdc must match the discovered price. @@ -154,7 +156,7 @@ bash scripts/ci/repo_hygiene_checks.sh bash scripts/ci/security_checks.sh ``` -Live parity E2E is gated and targets staging by default: +Live parity E2E is gated and targets the staging sandbox by default: ```bash export SYNAPSE_OWNER_PRIVATE_KEY=0x... diff --git a/python/examples/consumer_call_provider.py b/python/examples/consumer_call_provider.py index 11616c9..c077f65 100644 --- a/python/examples/consumer_call_provider.py +++ b/python/examples/consumer_call_provider.py @@ -26,8 +26,8 @@ def parse_args() -> argparse.Namespace: ) parser.add_argument( "--environment", - default=os.getenv("SYNAPSE_ENV", "staging").strip() or "staging", - help="Gateway environment preset. Defaults to staging.", + default=os.getenv("SYNAPSE_ENV", "prod").strip() or "prod", + help="Gateway environment preset. Defaults to prod.", ) parser.add_argument( "--gateway-url", diff --git a/python/examples/consumer_wallet_to_invoke.py b/python/examples/consumer_wallet_to_invoke.py index c51810b..0d4fe31 100644 --- a/python/examples/consumer_wallet_to_invoke.py +++ b/python/examples/consumer_wallet_to_invoke.py @@ -20,12 +20,12 @@ def parse_args() -> argparse.Namespace: parser = argparse.ArgumentParser( - description="Create a staging owner wallet, issue an agent credential, and invoke a free service.", + description="Create a production owner wallet, issue an agent credential, and invoke a free service.", ) parser.add_argument( "--environment", - default=os.getenv("SYNAPSE_ENV", "staging").strip() or "staging", - help="Gateway environment preset. Defaults to staging.", + default=os.getenv("SYNAPSE_ENV", "prod").strip() or "prod", + help="Gateway environment preset. Defaults to prod.", ) parser.add_argument( "--gateway-url", diff --git a/python/examples/e2e.py b/python/examples/e2e.py index 85e5a9d..8f26364 100644 --- a/python/examples/e2e.py +++ b/python/examples/e2e.py @@ -73,7 +73,7 @@ def new_client(credential: str) -> SynapseClient: return SynapseClient( api_key=credential, gateway_url=os.getenv("SYNAPSE_GATEWAY_URL") or None, - environment="staging", + environment=os.getenv("SYNAPSE_ENV", "prod"), ) diff --git a/python/examples/free_service_smoke.py b/python/examples/free_service_smoke.py index 16b17cf..54ee3cb 100644 --- a/python/examples/free_service_smoke.py +++ b/python/examples/free_service_smoke.py @@ -18,7 +18,7 @@ def main() -> None: client = SynapseClient( api_key=require_env("SYNAPSE_AGENT_KEY"), gateway_url=os.getenv("SYNAPSE_GATEWAY_URL") or None, - environment="staging", + environment=os.getenv("SYNAPSE_ENV", "prod"), ) services = client.search(SYNAPSE_ECHO_SERVICE_ID, limit=10) service = next( diff --git a/python/examples/llm_smoke.py b/python/examples/llm_smoke.py index 8a7eb44..a6f8e05 100644 --- a/python/examples/llm_smoke.py +++ b/python/examples/llm_smoke.py @@ -12,7 +12,7 @@ def main() -> None: client = SynapseClient( api_key=require_env("SYNAPSE_AGENT_KEY"), gateway_url=os.getenv("SYNAPSE_GATEWAY_URL") or None, - environment="staging", + environment=os.getenv("SYNAPSE_ENV", "prod"), ) service_id = os.getenv("SYNAPSE_E2E_LLM_SERVICE_ID", "svc_deepseek_chat") max_cost_usdc = os.getenv("SYNAPSE_E2E_LLM_MAX_COST_USDC", "0.010000") diff --git a/python/examples/provider_staging_onboarding.py b/python/examples/provider_staging_onboarding.py index 1565b3f..f574b40 100644 --- a/python/examples/provider_staging_onboarding.py +++ b/python/examples/provider_staging_onboarding.py @@ -14,7 +14,7 @@ def parse_args() -> argparse.Namespace: parser = argparse.ArgumentParser( - description="Register a provider service on the SynapseNetwork staging gateway.", + description="Register a provider service on the SynapseNetwork production gateway.", ) parser.add_argument( "--provider-private-key", @@ -23,8 +23,8 @@ def parse_args() -> argparse.Namespace: ) parser.add_argument( "--environment", - default=os.getenv("SYNAPSE_ENV", "staging").strip() or "staging", - help="Gateway environment preset. Defaults to staging.", + default=os.getenv("SYNAPSE_ENV", "prod").strip() or "prod", + help="Gateway environment preset. Defaults to prod.", ) parser.add_argument( "--gateway-url", @@ -34,7 +34,7 @@ def parse_args() -> argparse.Namespace: parser.add_argument( "--endpoint-url", required=True, - help="Public HTTPS provider invoke endpoint reachable by the staging gateway.", + help="Public HTTPS provider invoke endpoint reachable by the Synapse gateway.", ) parser.add_argument( "--service-name", @@ -49,7 +49,7 @@ def parse_args() -> argparse.Namespace: parser.add_argument( "--price-usdc", default="0", - help="Fixed service price in USDC. Defaults to 0 for staging smoke tests.", + help="Fixed service price in USDC. Defaults to 0 for smoke tests.", ) parser.add_argument( "--provider-display-name", @@ -81,7 +81,7 @@ def validate_args(args: argparse.Namespace) -> int: endpoint_url = args.endpoint_url.strip() if not endpoint_url.startswith("https://"): print( - "--endpoint-url must be a public HTTPS URL. The staging gateway cannot invoke localhost.", + "--endpoint-url must be a public HTTPS URL. The Synapse gateway cannot invoke localhost.", file=sys.stderr, ) return 2 @@ -124,14 +124,14 @@ def main() -> int: description_for_model=args.description, provider_display_name=args.provider_display_name, tags=args.tags, - governance_note=f"sdk provider staging example {uuid4().hex[:8]}", + governance_note=f"sdk provider example {uuid4().hex[:8]}", ) print(f"Registered service id: {registered.service_id}") print_json("Registered service", registered.model_dump(by_alias=True, exclude_none=True)) status = provider.get_service_status(registered.service_id) print_json("Provider service status", status.model_dump(by_alias=True, exclude_none=True)) - print("Provider staging onboarding completed.") + print("Provider onboarding completed.") return 0 except AuthenticationError as exc: print(f"Authentication failed: {exc}", file=sys.stderr) diff --git a/python/examples/smoke_test.py b/python/examples/smoke_test.py index 3021f55..f12c7bf 100755 --- a/python/examples/smoke_test.py +++ b/python/examples/smoke_test.py @@ -41,7 +41,7 @@ def parse_args() -> argparse.Namespace: parser.add_argument( "--environment", default=os.getenv("SYNAPSE_ENV", "").strip(), - help="Gateway environment preset. Defaults to staging.", + help="Gateway environment preset. Defaults to prod.", ) parser.add_argument( "--query", diff --git a/python/synapse_client/config.py b/python/synapse_client/config.py index 2e3fa90..94ddd1d 100644 --- a/python/synapse_client/config.py +++ b/python/synapse_client/config.py @@ -10,7 +10,7 @@ "prod": "https://api.synapse-network.ai", } -DEFAULT_ENVIRONMENT: SynapseEnvironment = "staging" +DEFAULT_ENVIRONMENT: SynapseEnvironment = "prod" def resolve_gateway_url( diff --git a/python/synapse_client/test/test_auth_unit.py b/python/synapse_client/test/test_auth_unit.py index 657bbb0..dd47d76 100644 --- a/python/synapse_client/test/test_auth_unit.py +++ b/python/synapse_client/test/test_auth_unit.py @@ -108,7 +108,7 @@ def fake_request(method, url, headers, json, timeout): ] -def test_auth_defaults_to_staging_gateway(monkeypatch): +def test_auth_defaults_to_prod_gateway(monkeypatch): monkeypatch.delenv("SYNAPSE_GATEWAY", raising=False) monkeypatch.delenv("SYNAPSE_ENV", raising=False) @@ -117,7 +117,7 @@ def test_auth_defaults_to_staging_gateway(monkeypatch): signer=lambda message: "0xsigned", ) - assert auth.gateway_url == "https://api-staging.synapse-network.ai" + assert auth.gateway_url == "https://api.synapse-network.ai" def test_issue_credential_and_balance_use_bearer_token(monkeypatch): diff --git a/python/synapse_client/test/test_client_unit.py b/python/synapse_client/test/test_client_unit.py index 94b3f69..5d18f4f 100644 --- a/python/synapse_client/test/test_client_unit.py +++ b/python/synapse_client/test/test_client_unit.py @@ -85,11 +85,11 @@ def test_client_uses_synapse_gateway_env(monkeypatch): assert client.gateway_url == "https://gateway.example" -def test_resolve_gateway_url_defaults_to_staging(monkeypatch): +def test_resolve_gateway_url_defaults_to_prod(monkeypatch): monkeypatch.delenv("SYNAPSE_GATEWAY", raising=False) monkeypatch.delenv("SYNAPSE_ENV", raising=False) - assert resolve_gateway_url() == "https://api-staging.synapse-network.ai" + assert resolve_gateway_url() == "https://api.synapse-network.ai" def test_resolve_gateway_url_supports_presets_and_explicit_override(monkeypatch): diff --git a/scripts/ci/python_checks.sh b/scripts/ci/python_checks.sh index 390ff16..9b65336 100755 --- a/scripts/ci/python_checks.sh +++ b/scripts/ci/python_checks.sh @@ -4,7 +4,7 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" cd "$ROOT_DIR" -export SYNAPSE_ENV=staging +export SYNAPSE_ENV=prod unset SYNAPSE_GATEWAY PYTHON_BIN="${PYTHON_BIN:-python}" diff --git a/scripts/ci/repo_hygiene_checks.sh b/scripts/ci/repo_hygiene_checks.sh index 37aac9b..14885f9 100755 --- a/scripts/ci/repo_hygiene_checks.sh +++ b/scripts/ci/repo_hygiene_checks.sh @@ -12,9 +12,19 @@ if grep -RInF --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv exit 1 fi -echo "[ci:hygiene] checking public preview staging defaults" +echo "[ci:hygiene] checking production defaults" grep -RIn --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv \ - "https://api-staging.synapse-network.ai" README.md docs python/synapse_client typescript/src typescript/tests >/dev/null + "https://api.synapse-network.ai" README.md README.zh-CN.md docs llms.txt llm-instructions.md python/synapse_client typescript/src >/dev/null +grep -RIn --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv \ + "https://docs.synapse-network.ai/sdks" README.md README.zh-CN.md docs llms.txt >/dev/null +grep -RIn --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv \ + "https://www.synapse-network.ai" README.md README.zh-CN.md docs llms.txt >/dev/null +if grep -RInE --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=dist --exclude-dir=build --exclude-dir=coverage --exclude-dir=.pytest_cache \ + '(Production docs are reserved|Production docs .*预留|production launch will switch|生产环境上线后,再把公开示例|Public Preview default|Public Preview 默认|staging\.synapse-network\.ai/docs)' \ + README.md README.zh-CN.md docs llms.txt llm-instructions.md; then + echo "[ci:hygiene] stale staging-first or reserved-production docs detected" >&2 + exit 1 +fi echo "[ci:hygiene] checking npm package scope" OLD_NPM_SCOPE="@synapse-network""/" @@ -27,7 +37,7 @@ fi echo "[ci:hygiene] checking removed local gateway guidance" if grep -RInE --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=dist --exclude-dir=build --exclude-dir=coverage --exclude-dir=.pytest_cache \ '(127\.0\.0\.1:8000|localhost:8000|scripts/local|Hardhat)' README.md README.zh-CN.md docs python/synapse_client/test typescript/tests; then - echo "[ci:hygiene] local gateway guidance detected; public tests and docs must point to staging" >&2 + echo "[ci:hygiene] local gateway guidance detected; public tests and docs must point to production or the staging sandbox" >&2 exit 1 fi if grep -RInE --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=dist --exclude-dir=build --exclude-dir=coverage --exclude-dir=.pytest_cache \ @@ -36,7 +46,7 @@ if grep -RInE --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv exit 1 fi -echo "[ci:hygiene] checking public SDK examples use staging agent credentials" +echo "[ci:hygiene] checking public SDK examples use agent credentials" if grep -RInF --exclude-dir=.git --exclude-dir=__pycache__ --exclude-dir=.pytest_cache \ "SYNAPSE_API_KEY" python/examples; then echo "[ci:hygiene] public examples must use SYNAPSE_AGENT_KEY, not SYNAPSE_API_KEY" >&2 diff --git a/typescript/examples/_shared.ts b/typescript/examples/_shared.ts index 182d91b..827e492 100644 --- a/typescript/examples/_shared.ts +++ b/typescript/examples/_shared.ts @@ -1,5 +1,5 @@ import { AuthenticationError, InvokeError, SynapseClient } from "../src"; -import type { ServiceRecord } from "../src"; +import type { ServiceRecord, SynapseEnvironment } from "../src"; export const SYNAPSE_ECHO_SERVICE_ID = "svc_synapse_echo"; export const DEFAULT_FIXED_PAYLOAD: Record = { @@ -25,10 +25,17 @@ export function client(credential = requireEnv("SYNAPSE_AGENT_KEY")): SynapseCli return new SynapseClient({ credential, gatewayUrl: gatewayUrl || undefined, - environment: gatewayUrl ? undefined : "staging", + environment: gatewayUrl ? undefined : envPreset(), }); } +function envPreset(): SynapseEnvironment { + const value = process.env.SYNAPSE_ENV?.trim(); + if (!value) return "prod"; + if (value === "prod" || value === "staging") return value; + throw new Error(`unsupported SYNAPSE_ENV: ${value}`); +} + export function requireEnv(name: string): string { const value = process.env[name]?.trim(); if (!value) throw new Error(`${name} is required`); diff --git a/typescript/src/config.ts b/typescript/src/config.ts index 1323e53..d804430 100644 --- a/typescript/src/config.ts +++ b/typescript/src/config.ts @@ -1,6 +1,6 @@ import type { SynapseEnvironment } from "./types"; -export const DEFAULT_ENVIRONMENT: SynapseEnvironment = "staging"; +export const DEFAULT_ENVIRONMENT: SynapseEnvironment = "prod"; export const GATEWAY_URLS: Record = { staging: "https://api-staging.synapse-network.ai", diff --git a/typescript/src/types.ts b/typescript/src/types.ts index db36111..3c6b578 100644 --- a/typescript/src/types.ts +++ b/typescript/src/types.ts @@ -3,7 +3,7 @@ export type SynapseEnvironment = "staging" | "prod"; export interface SynapseAuthOptions { - /** Gateway environment preset. Default: staging public preview. */ + /** Gateway environment preset. Default: production. */ environment?: SynapseEnvironment; /** Gateway base URL. Overrides environment when provided. */ gatewayUrl?: string; @@ -479,7 +479,7 @@ export interface InvocationResult { export interface SynapseClientOptions { /** Agent credential token (X-Credential header). Required. */ credential: string; - /** Gateway environment preset. Default: staging public preview. */ + /** Gateway environment preset. Default: production. */ environment?: SynapseEnvironment; /** Gateway base URL. Overrides environment when provided. */ gatewayUrl?: string; diff --git a/typescript/tests/unit/client.test.ts b/typescript/tests/unit/client.test.ts index 18c23a8..745a621 100644 --- a/typescript/tests/unit/client.test.ts +++ b/typescript/tests/unit/client.test.ts @@ -54,8 +54,8 @@ test("constructor accepts default gatewayUrl", () => { expect(client).toBeInstanceOf(SynapseClient); }); -test("resolveGatewayUrl defaults to staging public preview", () => { - expect(resolveGatewayUrl()).toBe("https://api-staging.synapse-network.ai"); +test("resolveGatewayUrl defaults to production", () => { + expect(resolveGatewayUrl()).toBe("https://api.synapse-network.ai"); }); test("resolveGatewayUrl supports presets and explicit override", () => { @@ -74,7 +74,7 @@ test("resolveGatewayUrl rejects removed local environment preset", () => { expect(() => resolveGatewayUrl({ environment: "local" as never })).toThrow("unsupported Synapse environment"); }); -test("SynapseAuth defaults to staging gateway", async () => { +test("SynapseAuth defaults to production gateway", async () => { const urls: string[] = []; (globalThis as unknown as Record).fetch = jest.fn(async (url: string) => { urls.push(url); @@ -96,7 +96,7 @@ test("SynapseAuth defaults to staging gateway", async () => { }); await auth.getToken(); - expect(urls[0]).toContain("https://api-staging.synapse-network.ai/api/v1/auth/challenge"); + expect(urls[0]).toContain("https://api.synapse-network.ai/api/v1/auth/challenge"); }); // ── invoke() — single-call path ───────────────────────────────────────────────