Skip to content

feat: add JSON API mode for account workflows #150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Loongphy wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat: add JSON API mode for account workflows #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,16 +66,20 @@ Detailed command documentation lives in [docs/commands/README.md](./docs/command

| Command | Description |
|---------|-------------|
| [`codex-auth list [--live] [--active] [--api\|--skip-api]`](./docs/commands/list.md) | List stored accounts and usage state |
| [`codex-auth list [--live] [--active] [--api\|--skip-api] [--json]`](./docs/commands/list.md) | List stored accounts and usage state |
| [`codex-auth login [--device-auth]`](./docs/commands/login.md) | Run `codex login`, then add the current account |
| [`codex-auth switch [--live] [--api\|--skip-api]`](./docs/commands/switch.md) | Switch the active account interactively |
| [`codex-auth switch <query>`](./docs/commands/switch.md) | Switch directly by row number or account selector |
| [`codex-auth switch <query> --json`](./docs/commands/switch.md) | Switch directly with JSON output |
| [`codex-auth remove [--live] [--api\|--skip-api]`](./docs/commands/remove.md) | Remove accounts interactively |
| [`codex-auth remove <query> [<query>...]`](./docs/commands/remove.md) | Remove accounts by selector |
| [`codex-auth remove --all`](./docs/commands/remove.md) | Remove all stored accounts |
| [`codex-auth remove (<query> [<query>...]\|--all) --json`](./docs/commands/remove.md) | Remove accounts with JSON output |
| [`codex-auth alias set <query> <alias>`](./docs/commands/alias.md) | Set an alias for an account |
| [`codex-auth alias clear <query>`](./docs/commands/alias.md) | Clear the alias for an account |

Machine-readable output for GUI integrations is documented in [docs/json-api.md](./docs/json-api.md).

### Import and Maintenance

| Command | Description |
Expand Down
26 changes: 13 additions & 13 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,49 +79,49 @@ That scope includes:

`chatgpt_user_id` is the user identity for this flow. A single user may have multiple workspace `chatgpt_account_id` values, and those values can be legacy account ids or organization fallback ids.

This means a `free`, `plus`, or `pro` record can still trigger a grouped Team-name refresh when it belongs to the same `chatgpt_user_id` as Team records.
This means a personal-plan record can still participate in a grouped workspace-name refresh when it belongs to the same `chatgpt_user_id` as Business, Enterprise, or Edu workspace records.

Account metadata refresh is attempted only when:

- the scope contains more than one record
- the scope contains at least one Team record
- at least one Team record in that scope still has `account_name = null`
- the scope contains at least one Business, Enterprise, or Edu workspace record
- at least one workspace record in that scope still has `account_name = null`

## Apply Rules

After a successful account metadata response:

- returned entries are matched by `chatgpt_account_id`
- matched records overwrite the stored `account_name`, even when a Team record already had an older value
- in-scope Team records, or in-scope records that already had an `account_name`, are cleared back to `null` when they are not returned by the response
- matched records overwrite the stored `account_name`, even when a workspace record already had an older value
- in-scope workspace records, or in-scope records that already had an `account_name`, are cleared back to `null` when they are not returned by the response
- records outside the scope are left unchanged

## Examples

Example 1:

- active record: `user@example.com / Team #1 / account_name = null`
- same grouped scope: `user@example.com / Team #2 / account_name = null`
- active record: `user@example.com / Business #1 / account_name = null`
- same grouped scope: `user@example.com / Business #2 / account_name = null`

Running `codex-auth list` should issue an account metadata request. If the API returns:

- `team-1 -> "Workspace Alpha"`
- `team-2 -> "Workspace Beta"`

Then both grouped Team records are updated.
Then both grouped Business workspace records are updated.

Example 2:

- active record: `user@example.com / Pro / account_name = null`
- same grouped scope: `user@example.com / Team #1 / account_name = null`
- same grouped scope: `user@example.com / Team #2 / account_name = "Old Workspace"`
- same grouped scope: `user@example.com / Business #1 / account_name = null`
- same grouped scope: `user@example.com / Business #2 / account_name = "Old Workspace"`

Running `codex-auth list` should still issue an account metadata request, because the grouped scope still has missing Team names. If the API returns:
Running `codex-auth list` should still issue an account metadata request, because the grouped scope still has missing workspace names. If the API returns:

- `team-1 -> "Prod Workspace"`
- `team-2 -> "Sandbox Workspace"`

Then:

- `Team #1` is filled with `Prod Workspace`
- `Team #2` is overwritten from `Old Workspace` to `Sandbox Workspace`
- `Business #1` is filled with `Prod Workspace`
- `Business #2` is overwritten from `Old Workspace` to `Sandbox Workspace`
Loading
Loading