# fish_greeting (updated for the J621 rewrite)

Shows a random library image as your shell greeting, using fastfetch. This is
the updated version of the script from
`J621-Django/extras/fish_greeting system/fish_greeting.fish`, adapted to the
new REST API.

## What changed from the old script

| | Old J621-Django | This version |
| --- | --- | --- |
| Endpoint | `GET /random/?rating=X` returned **image bytes** | `GET /api/random/?fastfetch=1&rating=X` returns **JSON** |
| Image access | same response, `X-File-MD5`/`X-File-Name` headers | signed `url` from the JSON, downloaded separately |
| Unsupported types | rolled again (recursion) | server only returns png/jpg/gif in fastfetch mode |
| Config | hardcoded `https://j621.jake.i` | `J621_BASE` / `J621_TOKEN` / `J621_WEB` |
| Printed link | `/view/<md5>` on the old host | `/detail/<J-ID>` on `J621_WEB` |
| Modes, logging, gifsicle, fastfetch flags | same | same (`~/.config/fish/greeting_mode`, `~/.config/j621Logos/logs.log`) |

The `gm-switch` helper and the `.desktop` launchers from the old repo keep
working unchanged: they write the same `~/.config/fish/greeting_mode` file
(0 = NSFW, 1 = SFW, 2 = Questionable).

## Install

```fish
cd extras/fish_greeting
fish install.fish
```

The installer copies the function into `~/.config/fish/functions/`, **asks for
your API origin** (and an optional scoped token — see below), writes
`~/.config/j621Greeting/config.fish` (mode 600, it may hold the token), checks
the tools it needs and then verifies the backend: `/health` must answer and a
random roll is attempted. It exits non-zero when the backend cannot be
reached.

It also appends a guarded block to `~/.config/fish/config.fish` that sources
the function. That is needed on setups whose distro/theme config (CachyOS,
Oh My Fish, hand-rolled `config.fish`) defines `fish_greeting` inline while
the shell starts — such a definition wins over autoloading from
`functions/`, so ours has to be loaded afterwards. The block is written once
and repeated installs leave it alone; pass `--no-config` to skip it.

Non-interactive / re-install:

```fish
fish install.fish --url https://j621.example.ts.net --token <api-token>
fish install.fish --no-prompt     # defaults, never asks
fish install.fish --force         # rewrite an existing config
```

Then test:

```fish
fish_greeting
```

Requirements: `curl` (or `wget`), `fastfetch`, `file`. Optional: `gifsicle`
(GIF downscaling), `jq` or `python3` (JSON parsing — without either it falls
back to grep/sed).

## No token? That is fine

The greeting is meant to run **without** a token: it then behaves like a
guest of your instance — unsigned image links and only items that are visible
to guests. Adding a token to the config unlocks signed links (useful when
something else fetches the URL for you) and items that are hidden from
guests.

## Configuration

Any of these work; the config file is read by the function on every run:

```fish
# ~/.config/j621Greeting/config.fish, or universal variables
set -g J621_BASE https://j621.rainbow-herring.ts.net   # API origin
set -g J621_WEB  https://j621.example.ts.net           # link origin (split deploys)
set -g J621_TOKEN <api token>                          # signed URLs + hidden items
set -g J621_FASTFETCH_CONFIG jake                      # fastfetch config name
```

`J621_TOKEN` is optional. The recommended value is a **scoped greeting
token**: open the app, go to *Account → Shell tokens* (or `/tokens`), create
one and copy the `j621r_…` key — it only works with `/api/random/`, so it is
safe to keep in this config. It also gives you signed image URLs and access
to items that are hidden from guests. Without a token the greeting runs as a
guest and sees the public library only.

## Rating filters

| `greeting_mode` | Rating requested | Label |
| --- | --- | --- |
| `0` | `e` | NSFW |
| `1` | `s` | SFW |
| `2` (default) | `q` | Questionable |

## Troubleshooting

- **The distro/theme greeting still shows** (CachyOS, Oh My Fish, …): those
  configs define `fish_greeting` while the shell starts, which beats
  autoloading. Check what fish resolved:
  `functions --details fish_greeting` — it must point at
  `~/.config/fish/functions/fish_greeting.fish`. If it points at a distro
  file, run `fish install.fish` again (it adds the source block to
  `config.fish`) or add it yourself:
  ```fish
  if test -f ~/.config/fish/functions/fish_greeting.fish
      source ~/.config/fish/functions/fish_greeting.fish
  end
  ```
  at the **end** of `~/.config/fish/config.fish`.
- `No logo (No image matches those filters.)` — the library has no images for
  that rating; try another mode or add files.
- `No logo (API error)` — check `J621_BASE`, and that the deployment is up
  (`https://<host>/health`).
- `No logo (download failed)` — the signed URL expired (they last 24 h) or the
  item was deleted between the two requests; just run it again.
- The greeting is slow — the API and image fetch have `--max-time` guards; a
  slow tailnet link is usually the cause.