https://github.com/minagishl/s3s-next
Modern TypeScript implementation of s3s for SplatNet 3 exports, usable as both a CLI and JavaScript module.
https://github.com/minagishl/s3s-next
cli graphql monorepo nintendo-switch nodejs s3s splatnet splatoon3 statink typescript
Last synced: 25 days ago
JSON representation
Modern TypeScript implementation of s3s for SplatNet 3 exports, usable as both a CLI and JavaScript module.
- Host: GitHub
- URL: https://github.com/minagishl/s3s-next
- Owner: minagishl
- License: gpl-3.0
- Created: 2026-06-25T16:46:53.000Z (29 days ago)
- Default Branch: main
- Last Pushed: 2026-06-25T19:01:42.000Z (29 days ago)
- Last Synced: 2026-06-25T19:07:41.897Z (29 days ago)
- Topics: cli, graphql, monorepo, nintendo-switch, nodejs, s3s, splatnet, splatoon3, statink, typescript
- Language: TypeScript
- Homepage:
- Size: 86.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# S3S Next
Modern TypeScript implementation of s3s-compatible SplatNet 3 exporting tools. Provides both a command-line interface and reusable JavaScript APIs for authentication, SplatNet data fetching, and stat.ink uploading.
Successor to the broken [s3s](https://github.com/frozenpandaman/s3s) / [s3si.ts](https://github.com/spacemeowx2/s3si.ts) workflow, with NSO 3.0.1+ encrypted Coral API support.
## Monorepo packages
| Package | Description |
| -------------------- | ------------------------------------------- |
| `s3s-next` | CLI binary |
| `@s3s-next/core` | High-level `S3SNextClient` |
| `@s3s-next/auth` | Nintendo Account / Coral / bulletToken auth |
| `@s3s-next/splatnet` | SplatNet 3 GraphQL client |
| `@s3s-next/statink` | stat.ink upload + mapper |
| `@s3s-next/storage` | profile.json, cache, migration |
## Setup
```bash
pnpm install
pnpm build
```
## Quick start
NSO 3.4+ requires the public [nxapi-znca-api](https://github.com/samuelthomas2774/nxapi-znca-api) for encrypted Coral requests. **One-time nxapi registration** is the recommended path for most users.
```bash
# 1. Configure profile (nxapi OAuth + optional stat.ink key)
pnpm exec s3s-next setup
# 2. Log in to Nintendo Account and refresh tokens
pnpm exec s3s-next auth
# 3. Upload missing battles (s3s -r equivalent)
pnpm exec s3s-next -r
```
Copy [`profile.json.example`](profile.json.example) to `profile.json` if you prefer editing by hand.
### nxapi registration (one-time)
NSO 3.4+ needs a personal nxapi-auth OAuth client. Use **Register** to create your own — do not reuse a client that was already listed on the page before you registered.
#### Step-by-step
1. Open https://nxapi-auth.fancy.org.uk/oauth/clients
2. Sign in with **Discord** or a **passkey** if prompted
3. Click **Register** to create a **new** client (do **not** open an existing client row)
4. Enable these scopes (all three required):
| Scope | Purpose |
| ------- | --------------------------- |
| `ca:gf` | f-parameter generation |
| `ca:er` | Encrypt Coral API requests |
| `ca:dr` | Decrypt Coral API responses |
5. Finish registration and copy **your** new Client ID
6. Run `s3s-next setup` and paste that Client ID; **leave clientSecret blank** (registered clients are usually public)
#### Common mistakes
| Do not use | Why |
| -------------------------------------------------- | ------------------------------------------------------- |
| Client ID from an existing row on the clients page | Only clients you create via Register work with s3s-next |
| “Shared secret” under Client authentication | JWT assertion only — s3s-next does not use it |
| Missing “Client secrets” section | Normal for public clients — secret is not required |
Or add to `profile.json` manually (no `clientSecret` needed for public clients):
```json
{
"fGen": {
"provider": "nxapi",
"url": "https://nxapi-znca-api.fancy.org.uk/api/znca",
"clientId": "your-client-id-from-register"
},
"statInkApiKey": "your-43-character-key"
}
```
Do not commit `profile.json` or secrets to git.
## s3s-compatible flags
```bash
s3s-next -r # upload missing
s3s-next -M [seconds] # monitor (default 300s)
s3s-next -r -M # both
s3s-next -nsr # skip Salmon Run
s3s-next -osr # Salmon Run only
s3s-next --blackout # mask other player names
```
## Commands
```bash
s3s-next setup # interactive profile setup (recommended first step)
s3s-next auth # Nintendo login + token refresh
s3s-next tokens # refresh gToken / bulletToken only
s3s-next import-tokens # manual token import (advanced)
s3s-next upload
s3s-next run
s3s-next monitor [seconds]
s3s-next fetch --json
s3s-next export
s3s-next migrate-s3s ./config.txt
s3s-next migrate-s3si ./profile.json
```
## Library usage
```typescript
import { S3SNextClient } from '@s3s-next/core';
const client = new S3SNextClient({
profilePath: './profile.json',
statInkApiKey: process.env.STATINK_API_KEY,
});
await client.login();
await client.uploadMissing();
```
Low-level APIs:
```typescript
import { createNintendoAuthClient } from '@s3s-next/auth';
import { createSplatNetClient } from '@s3s-next/splatnet';
import { createStatInkClient } from '@s3s-next/statink';
```
## Migrate from s3s / s3si.ts
```bash
s3s-next migrate-s3s ./config.txt -o ./profile.json
s3s-next migrate-s3si ./profile.json
```
## Manual token import (advanced)
If automatic token generation is not an option, import gToken (and optionally bulletToken) captured via mitmproxy or similar:
```bash
s3s-next import-tokens "" --bullet ""
```
This sets `fGen.provider` to `manual`. Tokens expire sooner than the nxapi flow; re-import when uploads fail. See [s3s mitmproxy wiki](https://github.com/frozenpandaman/s3s/wiki/mitmproxy-instructions) for capture methods (environment-dependent).
## Privacy
Using nxapi f-generation sends your Nintendo Account `id_token` to a third-party server (same trade-off as s3s). See [s3s token generation](https://github.com/frozenpandaman/s3s#token-generation-).
## Release
Push a semver tag to publish `s3s-next` to npm (OIDC trusted publishing via `.github/workflows/release.yml`):
```bash
# optional: bump packages/cli/package.json to match the tag
git tag v1.0.0
git push origin v1.0.0
```
The workflow sets `packages/cli/package.json` version from the tag, runs checks, builds, and publishes.
## Development
```bash
pnpm install
pnpm build
pnpm test
pnpm typecheck
```
## Credits
- [s3s](https://github.com/frozenpandaman/s3s) by frozenpandaman
- [s3si.ts](https://github.com/spacemeowx2/s3si.ts)
- [nxapi](https://github.com/samuelthomas2774/nxapi) for encrypted Coral API reference
## License
GPL-3.0 — see [LICENSE](LICENSE).