From 0817c9e4178d9dc4aab59773ddfad87b887d623a Mon Sep 17 00:00:00 2001 From: John Doe Date: Wed, 6 May 2026 03:30:49 +0000 Subject: [PATCH] Add LICENSE, AGENTS.md, and richer package.json metadata Make the published npm package easier to discover and consume: - LICENSE (MIT) so the published tarball ships with explicit terms. - AGENTS.md is the dedicated agent-facing playbook covering install, the typed client surface, auth, error handling, and rate limits. - package.json gains an English description, license=MIT, an uapis.cn homepage, an issues URL, and npm-search-friendly keywords (uapi, uapis.cn, sdk, typescript, public-api, openapi, ...). No code changes; build/publish pipeline is unaffected. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- AGENTS.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 21 ++++++++++++++ package.json | 26 ++++++++++++++++- 3 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 LICENSE diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6811a33 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,80 @@ +# AGENTS.md — uapi-sdk-typescript + +This file tells AI coding agents how to use the **official TypeScript / +Node.js SDK** for the [uapis.cn](https://uapis.cn) public API platform. + +## What this package is + +Strongly-typed Node / browser-compatible client for UAPI. Generated from the +live OpenAPI 3.1 spec at — so the method +list, parameter shapes, and return types stay in lock-step with the real +API. + +```bash +npm i uapi-sdk-typescript +# or +pnpm add uapi-sdk-typescript +# or +yarn add uapi-sdk-typescript +``` + +## Quick start + +```ts +import { UapiClient } from "uapi-sdk-typescript"; + +// Free-tier endpoints don't need an API key +const client = new UapiClient("https://uapis.cn"); + +const weather = await client.misc.getMiscWeather({ city: "北京" }); +console.log(weather); + +// Paid endpoints take a key +const paid = new UapiClient("https://uapis.cn", process.env.UAPI_KEY!); +const ocr = await paid.image.postImageOcr({ url: "https://…/photo.png" }); +``` + +The client is grouped by tag (`misc`, `network`, `text`, `image`, `social`, +`translate`, `search`, …) and each method name matches the underlying +`operationId` from the OpenAPI spec. + +## Discovery + +When generating code, agents should: + +1. Pull the spec from if the schema you need + isn't already in your local types. +2. Map the operation's `operationId` to a SDK method (`get-misc-weather` → + `client.misc.getMiscWeather`). +3. Pass the request parameters as a single object — query params, path + params, and body all live there. + +## Authentication + +- Many UAPI endpoints (network, text, random, convert, weather, time, + hotboard) work with no key. +- Paid endpoints want `X-API-Key`. The SDK forwards the second + `UapiClient` constructor argument to that header. +- For human-in-the-loop OAuth flows, see + . + +## Errors + +Every method throws an `AxiosError`-shaped error on non-2xx responses. The +error body is a JSON object: `{code, success: false, error, request_id?}`. +Surface the `error` text verbatim. + +## Rate limits + +Headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, +`Retry-After` are returned on every response. Honor them — back off on +`429` and obey `Retry-After`. + +## Related repos + +- MCP server: — same endpoints as MCP tools. +- Skills bundle: — markdown + skills for AI agents that prefer SKILL-driven workflows. +- Browser-only SDK: . +- Other languages: `uapi-sdk-python`, `uapi-sdk-go`, `uapi-sdk-rust`, + `uapi-sdk-java`, `uapi-sdk-csharp`, `uapi-sdk-cpp`, `uapi-sdk-php`. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4e7b5fa --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 AxT-Team / UAPI + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/package.json b/package.json index 5f23d3a..ec97b85 100644 --- a/package.json +++ b/package.json @@ -24,5 +24,29 @@ "devDependencies": { "typescript": "^5.4.0", "@types/node": "^20.11.0" - } + }, + "description": "Official TypeScript / Node.js SDK for UAPI / uapis.cn — a strongly-typed wrapper around 100+ free public-API endpoints (network, text, image, social, translation, search). Generated from the live OpenAPI 3.1 spec.", + "homepage": "https://uapis.cn/docs/sdk/typescript", + "bugs": { + "url": "https://github.com/AxT-Team/uapi-sdk-typescript/issues" + }, + "author": "UAPI ", + "license": "MIT", + "keywords": [ + "uapi", + "uapis", + "uapis.cn", + "sdk", + "typescript", + "nodejs", + "public-api", + "free-api", + "rest", + "rest-api", + "openapi", + "axios", + "client", + "agent", + "mcp" + ] }