@getmikan/sdk 0.0.0-stage → 0.5.201-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/NOTICE.md ADDED
@@ -0,0 +1,23 @@
1
+ # mikan: copyright, additional terms and credits
2
+
3
+ mikan
4
+ Copyright (C) 2026 Miroshka and Mikan
5
+ <https://github.com/Miroshka000/mikan>
6
+
7
+ mikan is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation ([LICENSE](LICENSE)), with the additional terms below. It is distributed WITHOUT ANY WARRANTY; see the GNU General Public License for details.
8
+
9
+ ## Additional terms (GNU GPL v3, section 7)
10
+
11
+ These terms apply to mikan as a whole and to every copy and modified version of it:
12
+
13
+ 1. **Attribution, section 7(b).** Copies and modified versions must keep the copyright notice above and a link to <https://github.com/Miroshka000/mikan>, in this file and wherever the program shows its authorship.
14
+ 2. **No passing off, section 7(c).** A modified version must be clearly marked as changed and as different from the original, and must not be presented as mikan or as an official mikan release.
15
+ 3. **Names and logos, section 7(e).** No rights are granted to the name "mikan" or to the mikan logo and mascot. A modified version must use another name and another logo. See [TRADEMARK.md](TRADEMARK.md).
16
+
17
+ ## Third-party code
18
+
19
+ - **[mihomo](https://github.com/MetaCubeX/mihomo)**, GPL-3.0, by MetaCubeX and contributors: the proxy core mikan runs.
20
+ - **[3x-ui](https://github.com/MHSanaei/3x-ui)**, GPL-3.0, by MHSanaei and contributors: parts of mikan are adapted from it, among them the local Happ crypt links (`internal/panel/subsrc/happcrypt.go`, after MHSanaei/3x-ui#6494, with the key from [Omegaplexx/hpwnr](https://github.com/Omegaplexx/hpwnr)).
21
+ - **Fonts:** Unbounded, Onest and JetBrains Mono, SIL Open Font License 1.1.
22
+
23
+ The other libraries mikan builds with keep their own licenses, listed in `go.mod`, `web/package.json` and `installer/Cargo.toml`.
package/README.md CHANGED
@@ -1,3 +1,36 @@
1
- # Temporary Holding Version
1
+ # @getmikan/sdk
2
2
 
3
- 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.
3
+ A typed TypeScript client for the API of the [mikan](https://github.com/Miroshka000/mikan) panel. The types are generated from the panel's own OpenAPI spec with [openapi-typescript](https://openapi-ts.dev/), the calls go through [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) (the pair the admin panel's own web client uses): a path, its method, and the parameters and bodies the API takes, all checked by the compiler.
4
+
5
+ Every stable release of the panel has an SDK of the same number: install the one that matches your panel (Settings → System → Updates shows it). npm versions have three numbers and a panel release has four, so npm's third is the panel's third times 100 plus its fourth: for a panel 0.5.2.1 the SDK is `0.5.201`, for 0.5.3.0 it is `0.5.300`. Name the version exactly, not a range.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ npm install @getmikan/sdk@<version>
11
+ ```
12
+
13
+ It needs Node 18 or later, or any runtime with `fetch`.
14
+
15
+ ## Sign in with an API key
16
+
17
+ Make a key in the panel: Settings → Security → API → New key. It looks like `mk_...` and is shown once. The client needs the key and the API address as the panel's API page shows it, `https://<panel>:<port>/<secret path>/api/v1`, with nothing after `/api/v1`.
18
+
19
+ ```ts
20
+ import { createClient } from "@getmikan/sdk";
21
+
22
+ const mikan = createClient({
23
+ baseUrl: "https://vpn.example.com:8443/SECRET-PATH/api/v1",
24
+ apiKey: process.env.MIKAN_API_KEY!,
25
+ });
26
+
27
+ const { data, error } = await mikan.GET("/users", {
28
+ params: { query: { state: "active", limit: 10 } },
29
+ });
30
+ if (error) throw new Error(error.detail);
31
+ for (const user of data.items) console.log(user.id, user.name);
32
+ ```
33
+
34
+ Every call gives `{ data, error, response }`: `data` on success, `error` as the problem document of RFC 9457 (`detail` holds the code of the error) on a refusal, and the `response` itself. The types of the API are exported too: `components["schemas"]["UserView"]`, `paths`, `operations`.
35
+
36
+ A key with "Read" access calls only GET, and the operations marked "session only" (sign-in, keys, balance changes) refuse every key with 403 `session_only`. The API page of the docs has the rest: <https://miroshka000.github.io/mikan/api/>.
@@ -0,0 +1,18 @@
1
+ import { type Client } from "openapi-fetch";
2
+ import type { paths } from "./schema.js";
3
+ export type { components, operations, paths } from "./schema.js";
4
+ export interface MikanOptions {
5
+ /**
6
+ * The API address of the panel, as its API page shows it, with no path after it:
7
+ * https://<panel>:<port>/<secret path>/api/v1
8
+ */
9
+ baseUrl: string;
10
+ /** An API key from Settings → Security → API: mk_... */
11
+ apiKey: string;
12
+ /** A fetch to use instead of the global one (tests, proxies, a runtime with its own). */
13
+ fetch?: typeof globalThis.fetch;
14
+ }
15
+ /** The typed client: GET, POST, PUT, PATCH and DELETE by the path of the API. */
16
+ export type MikanClient = Client<paths>;
17
+ /** A client that sends every request with the API key, as `Authorization: Bearer mk_...`. */
18
+ export declare function createClient({ baseUrl, apiKey, fetch }: MikanOptions): MikanClient;
package/dist/index.js ADDED
@@ -0,0 +1,19 @@
1
+ // The mikan panel API as a typed client. The types come from the panel's own OpenAPI
2
+ // spec (src/schema.ts, generated by openapi-typescript at build time); the calls go
3
+ // through openapi-fetch, the same pair the admin panel's web client is built on.
4
+ import createFetchClient, {} from "openapi-fetch";
5
+ /** A client that sends every request with the API key, as `Authorization: Bearer mk_...`. */
6
+ export function createClient({ baseUrl, apiKey, fetch }) {
7
+ if (!baseUrl)
8
+ throw new Error("@getmikan/sdk: baseUrl is empty, give the panel's API address");
9
+ if (!apiKey)
10
+ throw new Error("@getmikan/sdk: apiKey is empty, give an API key (mk_...)");
11
+ const client = createFetchClient({ baseUrl, fetch });
12
+ client.use({
13
+ onRequest({ request }) {
14
+ request.headers.set("Authorization", `Bearer ${apiKey}`);
15
+ return request;
16
+ },
17
+ });
18
+ return client;
19
+ }