create-stellar-service 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stellar Agent Services contributors
+
+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.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# create-stellar-service
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`npm create stellar-service` makes a project that sells an AI service on Stellar: agents pay per call in USDC through
+x402, under [Provider Standard v1](../../docs/provider-standard.md). The project runs, takes a paid testnet call and
+goes live as it comes, with no wallet needed until it goes live.
+
+```text
+$ npm create stellar-service
+
+Project folder [my-stellar-service]: captioner
+What are you making?
+  1. Wrap an API you already run, in any language (no code changes)
+  2. A new service in TypeScript
+  3. A new service in Python (FastAPI)
+Pick 1, 2 or 3 [1]: 1
+Your API's OpenAPI document, or the URL a paid call goes to [http://127.0.0.1:8000/openapi.json]:
+In one sentence, what does it offer? Agents search for it by these words and its name.
+[Enter: the document's]: Captions for product photos, in English and Turkish.
+What does a call cost, in USDC? [0.01]: 0.05
+```
+
+Then it writes the project and installs it. Next:
+
+```bash
+cd captioner
+npm run dev       # runs it here, paid to a throwaway testnet account: no wallet needed yet
+npm run try       # pays for one call with test money, from another terminal
+npm run launch    # goes live: one approval in your wallet, then Fly.io
+```
+
+`npm run launch` opens a page where your own wallet (Freighter, xBull, Albedo and others) approves the USDC trustline,
+the Stellar 8004 registration and a request for verification, in one go. Then it saves `PAY_TO` and `AGENT_ID`,
+deploys to Fly.io if you say yes, and waits until the service answers at its public address. `npm run status` shows
+where it stands at any time.
+
+The project depends on the Provider Kit released with this command. To try changes not released yet, run it from a
+clone of the repository, built once (`npm install && npm run build`):
+
+```bash
+node packages/create-stellar-service/dist/index.js captioner
+```
+
+From a clone, it packs the Provider Kit into the project's `vendor/` folder, so the project installs and builds by
+itself, in Docker too.
+
+## What it makes
+
+| Kind | You get |
+| --- | --- |
+| `wrap` | The [gateway](../provider-kit/README.md#gateway-mode) in front of an API you already run, in any language, with no code changes. With an OpenAPI document (FastAPI serves `/openapi.json`), `provider-kit init --openapi` makes a service of each POST endpoint it can call; without one, a starter service calls the URL you give. |
+| `typescript` | A new service with the [Provider Kit library](../provider-kit/README.md#library-in-short): `src/server.ts` and an example service to replace, `src/services/summarize.ts`. |
+| `python` | A new FastAPI app, `app.py`, with the gateway in front of it, and one container that runs both. |
+
+Every project has `.env` (the settings, kept out of git) and `.env.example`, a `Dockerfile` that keeps the job
+database on a volume at `/data`, a `fly.toml` for Fly.io, a `README.md`, and these scripts:
+
+| Script | What it does |
+| --- | --- |
+| `npm run dev` | Starts the service, or the gateway (and the Python kind's API), at http://localhost:8787. With `PAY_TO` empty it is paid to a throwaway testnet account ([`provider-kit dev`](../provider-kit/README.md#the-throwaway-payout-account)) |
+| `npm run try` | Pays for one call with test money, from a throwaway testnet account, and starts the service for it when it isn't running ([`provider-kit try`](../provider-kit/README.md#trying-a-paid-call)) |
+| `npm run check` | Checks the provider against the standard and shows how agents see it |
+| `npm run launch` | Takes it live: one page in your wallet for the trustline, the 8004 registration and verification, then the deploy ([`provider-kit launch`](../provider-kit/README.md#launching)) |
+| `npm run status` | Where it stands, from running here to verified, and the command to run next |
+| `npm run deploy` | Deploys again to Fly.io (`fly deploy`) |
+| `npm start` | Starts it for production: `PUBLIC_ORIGIN` must be your HTTPS origin |
+
+A gateway config reads `baseUrl`, `payTo`, `store` and the agent id from `.env` (`env:PUBLIC_ORIGIN`, `env:PAY_TO`,
+`env:JOB_DB_PATH`, `env:AGENT_ID`), so the same file runs on a laptop and in a container.
+
+**Fly.io.** `fly.toml` names the app after the folder, so the public address, `https://<app>.fly.dev`, is known before
+the first deploy: `launch` registers the service with it, writes `PUBLIC_ORIGIN`, `PAY_TO` and `AGENT_ID` under
+`[env]`, and deploys once. The job database lives on a volume Fly makes on the first deploy. Another host works too:
+`npm run launch -- --url https://your.domain --no-deploy`.
+
+**Python.** With [uv](https://docs.astral.sh/uv/) installed, `npm run dev` starts the API with
+`uv run --with-requirements requirements.txt`, so there is no virtual environment to make. Without it, the next steps
+give the two commands that make `.venv`.
+
+## Mainnet
+
+`--network mainnet` makes a project that takes real USDC on `stellar:pubnet`. What changes:
+
+- **The facilitator.** Payments settle through OpenZeppelin's facilitator, `https://channels.openzeppelin.com/x402`,
+  which Stellar's docs list for mainnet (x402.org's settles testnet only). It wants an API key: get one at
+  [channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen) and set `FACILITATOR_AUTH="Bearer <key>"` in
+  `.env`. A gateway config sends it as `"facilitatorHeaders": { "Authorization": "env:FACILITATOR_AUTH" }`; the
+  TypeScript service reads it in `src/server.ts`. Without it, the service stops at start and says so.
+- **The RPC.** `SOROBAN_RPC_URL` in `.env` starts as `https://mainnet.sorobanrpc.com`, the RPC the Stellar 8004 SDK
+  uses. Mainnet has no default one. For production traffic, an [RPC provider](https://developers.stellar.org/docs/data/apis/rpc/providers)'s
+  is safer.
+- **No test money.** There is no throwaway account and no `npm run try`. `npm run launch` sets up the account clients
+  pay in your own wallet, which needs a few XLM, and `npm run dev` runs once `PAY_TO` is set.
+- **The deploy.** `launch` stages `FACILITATOR_AUTH` and `SOROBAN_RPC_URL` as Fly secrets. A TypeScript service reads its
+  network from `STELLAR_NETWORK`, which `launch` also writes to `fly.toml`. It won't call a deploy live while it takes
+  payments on another network than the one it registered on.
+
+To take a testnet project to mainnet, make these changes by hand: in a gateway config, `network`, `facilitator`,
+`facilitatorHeaders` and `rpcUrl`; in a TypeScript project's `.env`, `STELLAR_NETWORK=stellar:pubnet`. In both, add
+`FACILITATOR_AUTH` and `SOROBAN_RPC_URL` to `.env`. Then empty `PAY_TO` and `AGENT_ID` (testnet's agent ids don't exist
+on mainnet), delete `DEV_PAY_TO`, and run `npm run launch`.
+
+## For scripts and coding agents
+
+Flags answer every question. Without a terminal it asks nothing, and `--kind` is needed:
+
+```bash
+create-stellar-service captioner --kind wrap --openapi http://127.0.0.1:8000/openapi.json \
+  --description "Captions for product photos, in English and Turkish." --price 0.05
+```
+
+| Flag | Answers |
+| --- | --- |
+| `--kind wrap\|typescript\|python` | What to make |
+| `--openapi <file \| url>` | The API's OpenAPI document (`wrap`). It is read first, so nothing is written for an API that isn't running. With a file whose servers are relative, `--upstream` is the API's base URL. |
+| `--upstream <url>` | Without `--openapi`: the URL a paid call goes to (`wrap`) |
+| `--description <text>` | One sentence on what it offers: search matches it and the name |
+| `--name <text>` | The provider's name. Default: the folder's, or the document's title. |
+| `--price <usdc>` | What a call costs, in USDC. Default `0.01`. |
+| `--network testnet\|mainnet` | Where clients pay. Default `testnet`, with test money. `mainnet` takes real USDC: see [Mainnet](#mainnet). |
+| `--wallet`, `--pay-to <G…>` | Set up the payout account now in your wallet, or use an address you have. Without either, nothing is needed until `npm run launch`. |
+| `--yes` | Take the defaults for the questions no flag answers |
+
+`--wallet` opens a page in the user's browser, so a coding agent asks the user first. It signs nothing itself. So
+does `npm run launch` later: a coding agent runs it with `--no-open` and gives the user the link.
+
+## Safety
+
+- **No secret key, anywhere.** It never asks for one, makes one or writes one. The payout account is set up in the
+  developer's own wallet, on `provider-kit launch`'s approval page, and only its public address is saved. Until then,
+  `npm run dev`'s throwaway testnet account has no key anyone keeps.
+- **It never pays.** `npm run try` pays later, when the developer runs it, from a throwaway account with test money.
+- **Testnet unless asked.** Every project starts on `stellar:testnet`; only `--network mainnet` makes a mainnet one.
+- **Nothing is overwritten.** It refuses a folder that already has files in it.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `src/main.ts` | The questions, the flags, and the run: write, install, the gateway config, the payout account if asked |
+| `src/files.ts` | The files each kind writes: `package.json` and its scripts, `.env`, the README, the Python kind's gateway config, and the templates filled in |
+| `src/kit.ts` | Where the Provider Kit comes from: a clone (packed into `vendor/`) or npm, and the npm overrides a project needs |
+| `src/index.ts` | The command |
+| `templates/` | The code and Dockerfiles each kind starts from, and `fly.toml` |

package/dist/files.d.ts

@@ -0,0 +1,133 @@
+export type Kind = "wrap" | "typescript" | "python";
+/** The network a project takes payments on, as its CAIP-2 id: testnet's test money, or mainnet's (pubnet) real USDC. */
+export type Network = "stellar:testnet" | "stellar:pubnet";
+/** The facilitator that verifies and settles a project's payments: x402.org's on testnet, OpenZeppelin's on mainnet. */
+export declare const FACILITATORS: Record<Network, string>;
+/** Where mainnet's facilitator gives out API keys. */
+export declare const FACILITATOR_KEYS = "https://channels.openzeppelin.com/gen";
+/** The Soroban RPC a mainnet project starts with: the one the Stellar 8004 SDK reads the registry through. */
+export declare const MAINNET_RPC = "https://mainnet.sorobanrpc.com";
+/** What a mainnet project also reads from .env, kept as secrets: the facilitator's API key, and an RPC URL, which may hold one. */
+export declare const MAINNET_SETTINGS: readonly ["FACILITATOR_AUTH", "SOROBAN_RPC_URL"];
+export declare const KINDS: Record<Kind, string>;
+/** What every kind's provider says until the developer writes their own: the template's service. */
+export declare const TEMPLATE_DESCRIPTION = "Summarizes English text for agents: the first sentences, with sentence and word counts.";
+/** The price a service starts with, in USDC, when none is given. */
+export declare const DEFAULT_PRICE = "0.01";
+/** The template service, as the Python kind's gateway config describes it. src/services/summarize.ts and app.py match it. */
+export declare const SUMMARIZE: {
+    name: string;
+    title: string;
+    description: string;
+    price: string;
+    charge: string;
+    expectedDurationSeconds: number;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            text: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                description: string;
+            };
+            sentences: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    outputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            summary: {
+                type: string;
+            };
+            sentences: {
+                type: string;
+                description: string;
+            };
+            words: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+    examples: {
+        input: {
+            text: string;
+            sentences: number;
+        };
+        output: {
+            summary: string;
+            sentences: number;
+            words: number;
+        };
+    }[];
+    capacity: {
+        concurrency: number;
+        maxQueueWaitSeconds: number;
+    };
+    upstream: {
+        url: string;
+    };
+};
+/** The settings every project reads from .env, which a gateway config names as "env:NAME". */
+export declare const SETTINGS: readonly ["PAY_TO", "PUBLIC_ORIGIN", "JOB_DB_PATH", "AGENT_ID"];
+export interface Project {
+    kind: Kind;
+    /** The folder's name, which is also the npm package name and the Docker image name. */
+    package: string;
+    /** The Fly.io app name in fly.toml: its public address is https://<app>.fly.dev. */
+    app: string;
+    name: string;
+    description: string;
+    /** Each service's price in USDC, such as "0.01". */
+    price: string;
+    network: Network;
+    /** Whether the kit's packages are in vendor/, packed from a clone. */
+    vendored: boolean;
+    /** Python: whether uv runs the API, so no virtual environment has to be made first. */
+    uv?: boolean;
+}
+/** The command that starts the Python kind's API on this computer: with uv when it is installed, else from .venv. */
+export declare function apiCommand(project: Pick<Project, "uv">): string;
+/** A file from templates/<directory>/, with every {{placeholder}} filled in. */
+export declare function template(directory: string, file: string, project: Project): string;
+/** The template files each kind copies: [template directory, file]. */
+export declare const TEMPLATE_FILES: Record<Kind, [string, string][]>;
+export declare function packageJson(project: Project, dependencies: Record<string, string>): string;
+/** The Python kind's gateway config: the template service in front of app.py, at the project's price. */
+export declare function pythonGatewayConfig(project: Project): string;
+/**
+ * A config `provider-kit init` wrote, made to run anywhere: baseUrl, store and the agent id from .env, no "dev" (npm run
+ * dev runs in development), the name, description and price given, and on mainnet its facilitator, key and RPC. Returns
+ * the config and the other variables it reads, such as the API key init named for an upstream header.
+ */
+export declare function adaptInitConfig(text: string, provider: {
+    name?: string;
+    description?: string;
+    price?: string;
+}, network?: Network): {
+    config: string;
+    variables: string[];
+};
+/** .env, or .env.example with `example`: the settings, and the variables a gateway config also reads. */
+export declare function envFile(project: Project, values: {
+    payTo?: string;
+    variables?: string[];
+}, example?: boolean): string;
+export declare function gitignore(project: Project): string;
+export declare function dockerignore(project: Project): string;
+/** The project's README: run it, try it, take it live, see where it stands, and make it yours. */
+export declare function readme(project: Project, options: {
+    services: string;
+    upstream?: string;
+}): string;
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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"}