# Shared files: what the users of an application exchange

An application published on jumphp.net can let its users **share files with each other**, without an account:
[WinZik](/winzik)'s skins and lyrics, a game's levels, palettes, templates… A file sent is **public at once**; the
owner of the project removes what does not belong there.

Each application chooses its **kinds** of files (`skin`, `lyrics`, `level`…: lower case letters, digits and dashes,
20 characters at most).

## The API

On the site (not on the games origin), CORS open: the applications' pages and the installed programs call it.

| Request | What it does |
|---|---|
| `GET /api/apps/<slug>/shared/<kind>?q=words&limit=200` | the list, newest first; `q` looks in the name, title, artist and author (every word, accents ignored) |
| `GET /api/apps/<slug>/shared/<kind>/<id>` | the file |
| `POST /api/apps/<slug>/shared/<kind>` | sends a file: JSON `{name, title?, artist?, author?, ext, data}` (`data` in base64) → its entry (201) |

An entry: `{id, name, title, artist, author, ext, size, sha256, at, downloads}`.

Limits: 4 MB a file, 300 MB an application, 20 sends an hour per address; extensions `zip`, `lyr`, `txt`, `json`,
`png`, `ogg`, `mp3`, `wav` (a `.zip` must be one). The same file sent twice is kept once. Errors: 400 (bad send),
413 (too big), 429 (too many sends), 404 (application not published).

## From PHP (JumPHP)

With `JumPHP\Http`: never blocking, the answer comes in a later frame.

```php
$base = 'https://jumphp.net/api/apps/my-app/shared';
$this->engine->http()->get("$base/level?q=" . rawurlencode('castle'))
    ->then(fn (HttpResponse $r) => $this->levels = $r->ok() ? $r->json()['items'] : []);

$this->engine->http()->post("$base/level", [
    'name' => 'The dungeon', 'author' => 'Ada', 'ext' => 'json', 'data' => base64_encode($json),
]);
```

WinZik is the complete example (`apps/winzik/src/Core/Market.php`: the marketplace of skins and lyrics, and the
lyrics looked for by themselves for each song).

## For the owner

The MCP tools of jumphp.net: `list_shared_files` (the kinds, then the files of a kind) and `delete_shared_file`
(remove a file).
