@tansy/storage-imgbb 0.0.0-stage → 0.1.0

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/CHANGELOG.md ADDED
@@ -0,0 +1,8 @@
1
+ # Changelog
2
+
3
+ What changed in each release of `@tansy/storage-imgbb`.
4
+
5
+ ## 0.1.0 — 2026-11-22
6
+
7
+ First release. Stores a site's pictures on imgbb, a free image host, and anything else in a
8
+ fallback adapter. Needs `tansy` ^0.1.2, for `storageIndex` from `tansy/storage`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mohamed Salah
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,13 @@
1
- # Temporary Holding Version
1
+ <!-- Generated by scripts/package-metadata.mjs. Change that script, not this file. -->
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
+ # @tansy/storage-imgbb
4
+
5
+ imgbb for tansy file storage: free image hosting for a public site's pictures.
6
+
7
+ ```bash
8
+ npm install @tansy/storage-imgbb
9
+ ```
10
+
11
+ Add it to `tansy.config.ts`. See [the storage guide](https://github.com/mhmdsalahsebai/tansy/blob/main/docs/guides/storage.md) for what it adds and the options it takes.
12
+
13
+ A first-party plugin for [tansy](https://github.com/mhmdsalahsebai/tansy), a self-hosted, runtime-schema CMS for Next.js. MIT licensed.
package/index.d.ts ADDED
@@ -0,0 +1,29 @@
1
+ import { type StorageAdapter, type StorageIndex } from "tansy/storage";
2
+ export interface ImgbbStorageOptions {
3
+ /** IMGBB_API_KEY, from https://api.imgbb.com. */
4
+ apiKey: string;
5
+ /**
6
+ * Where everything imgbb doesn't take goes: anything but a PNG, JPEG, GIF or WebP image, an
7
+ * image over 32 MB, or one imgbb would store changed. Without it, such an upload is refused.
8
+ */
9
+ fallback?: StorageAdapter;
10
+ /** Needed only when two imgbb accounts are in use at once, such as during a move. */
11
+ name?: string;
12
+ }
13
+ /** What the adapter keeps for each key: the image's address on imgbb, or nothing for one in the fallback. */
14
+ export interface ImgbbEntry {
15
+ url?: string;
16
+ size: number;
17
+ }
18
+ /**
19
+ * imgbb, a free image host, through its upload API. imgbb picks each image's address, so the adapter
20
+ * keeps it in a storage index, under core's key.
21
+ *
22
+ * Every image on imgbb is public to anyone holding its address. The CMS never hands that address
23
+ * out: it reads the image itself and serves it after its own access checks. But it can't be made
24
+ * private, so this suits a public site's pictures, not files that must stay private.
25
+ *
26
+ * imgbb has no API to delete an image, so a deleted file's image stays on imgbb, unreachable from
27
+ * the CMS, until removed by hand from the imgbb account.
28
+ */
29
+ export declare function imgbbStorage(options: ImgbbStorageOptions, index?: StorageIndex<ImgbbEntry>, fetcher?: typeof fetch): StorageAdapter;
package/index.js ADDED
@@ -0,0 +1,132 @@
1
+ import { bodyBlob, callProvider, rangeOf, storageIndex, StorageProviderError } from "tansy/storage";
2
+ const PROVIDER = "imgbb";
3
+ const UPLOAD = "https://api.imgbb.com/1/upload";
4
+ /** imgbb's own limit on one image. */
5
+ const MAX_BYTES = 32 * 1024 * 1024;
6
+ /** The raster images core serves inline, less AVIF, which imgbb isn't documented to take. */
7
+ const IMAGES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
8
+ /** Only imgbb's own image host, so a changed index entry can't send a read anywhere else. */
9
+ function imageUrl(value) {
10
+ if (typeof value !== "string")
11
+ return null;
12
+ try {
13
+ const url = new URL(value);
14
+ return url.protocol === "https:" && (url.hostname === "i.ibb.co" || url.hostname.endsWith(".ibb.co")) ? url : null;
15
+ }
16
+ catch {
17
+ return null;
18
+ }
19
+ }
20
+ function entryOf(value) {
21
+ if (!value || typeof value !== "object")
22
+ return null;
23
+ const { url, size } = value;
24
+ if (typeof size !== "number")
25
+ return null;
26
+ if (url === undefined)
27
+ return { size };
28
+ const address = imageUrl(url);
29
+ return address ? { url: address.href, size } : null;
30
+ }
31
+ /**
32
+ * imgbb, a free image host, through its upload API. imgbb picks each image's address, so the adapter
33
+ * keeps it in a storage index, under core's key.
34
+ *
35
+ * Every image on imgbb is public to anyone holding its address. The CMS never hands that address
36
+ * out: it reads the image itself and serves it after its own access checks. But it can't be made
37
+ * private, so this suits a public site's pictures, not files that must stay private.
38
+ *
39
+ * imgbb has no API to delete an image, so a deleted file's image stays on imgbb, unreachable from
40
+ * the CMS, until removed by hand from the imgbb account.
41
+ */
42
+ export function imgbbStorage(options, index, fetcher = fetch) {
43
+ const { apiKey, fallback, name = "imgbb" } = options;
44
+ const entries = index ?? storageIndex(name);
45
+ const read = async (key) => entryOf(await entries.get(key));
46
+ async function toFallback(key, body, put, why) {
47
+ if (!fallback) {
48
+ await body.cancel();
49
+ throw new Error(`imgbb storage can't keep this file: ${why}. Set a fallback adapter for it.`);
50
+ }
51
+ await fallback.put(key, body, put);
52
+ await entries.set(key, { size: put.size });
53
+ }
54
+ async function upload(key, blob) {
55
+ const form = new FormData();
56
+ form.set("image", blob, key.split("/").pop() || "image");
57
+ const url = new URL(UPLOAD);
58
+ url.searchParams.set("key", apiKey);
59
+ const response = await callProvider(PROVIDER, "upload", url, { method: "POST", body: form }, fetcher);
60
+ let answer;
61
+ try {
62
+ answer = await response.json();
63
+ }
64
+ catch {
65
+ throw new StorageProviderError(PROVIDER, "upload");
66
+ }
67
+ const address = imageUrl(answer.data?.image?.url ?? answer.data?.url);
68
+ if (!address)
69
+ throw new StorageProviderError(PROVIDER, "upload");
70
+ return { url: address.href, size: Number(answer.data?.size) };
71
+ }
72
+ return {
73
+ name,
74
+ assertUsable() {
75
+ if (!apiKey)
76
+ throw new Error("imgbb storage needs an API key (IMGBB_API_KEY).");
77
+ fallback?.assertUsable?.();
78
+ },
79
+ async put(key, body, put) {
80
+ const previous = await read(key);
81
+ if (!IMAGES.has(put.contentType)) {
82
+ await toFallback(key, body, put, `imgbb takes PNG, JPEG, GIF and WebP images only, not ${put.contentType}`);
83
+ }
84
+ else if (put.size > MAX_BYTES) {
85
+ await toFallback(key, body, put, "imgbb takes images up to 32 MB only");
86
+ }
87
+ else {
88
+ const blob = await bodyBlob(body, put.contentType);
89
+ const stored = await upload(key, blob);
90
+ // The CMS serves the size it recorded, so an image imgbb recompressed would be served cut short or padded.
91
+ if (stored.size !== put.size)
92
+ await toFallback(key, blob.stream(), put, "imgbb would store it changed");
93
+ else
94
+ await entries.set(key, { url: stored.url, size: put.size });
95
+ }
96
+ // Replacing what a restore puts back: the old copy in the fallback goes. One on imgbb can't.
97
+ if (previous && !previous.url) {
98
+ const now = await read(key);
99
+ if (now?.url)
100
+ await fallback?.delete(key);
101
+ }
102
+ },
103
+ async get(key, range) {
104
+ const entry = await read(key);
105
+ if (!entry)
106
+ return null;
107
+ if (!entry.url)
108
+ return fallback ? fallback.get(key, range) : null;
109
+ const response = await callProvider(PROVIDER, "read", entry.url, { headers: range ? { range: `bytes=${range.start}-${range.end}` } : {}, allow: [404] }, fetcher);
110
+ if (response.status === 404 || !response.body) {
111
+ await response.body?.cancel();
112
+ return null;
113
+ }
114
+ return rangeOf(response, range);
115
+ },
116
+ async delete(key) {
117
+ const entry = await read(key);
118
+ if (entry && !entry.url)
119
+ await fallback?.delete(key);
120
+ await entries.delete(key);
121
+ },
122
+ async list(prefix) {
123
+ const found = [];
124
+ for (const { key, value } of await entries.list(prefix)) {
125
+ const entry = entryOf(value);
126
+ if (entry)
127
+ found.push({ key, size: entry.size });
128
+ }
129
+ return found;
130
+ },
131
+ };
132
+ }
package/package.json CHANGED
@@ -1,6 +1,27 @@
1
1
  {
2
2
  "name": "@tansy/storage-imgbb",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "imgbb for tansy file storage: free image hosting for a public site's pictures.",
5
+ "keywords": [
6
+ "tansy",
7
+ "tansy-storage-adapter"
8
+ ],
9
+ "license": "MIT",
10
+ "author": "Mohamed Salah <mohamedsalahsebai@gmail.com>",
11
+ "homepage": "https://github.com/mhmdsalahsebai/tansy",
12
+ "repository": {
13
+ "type": "git",
14
+ "url": "git+https://github.com/mhmdsalahsebai/tansy.git",
15
+ "directory": "plugins/storage-imgbb"
16
+ },
17
+ "bugs": "https://github.com/mhmdsalahsebai/tansy/issues",
18
+ "exports": {
19
+ ".": {
20
+ "types": "./index.d.ts",
21
+ "default": "./index.js"
22
+ }
23
+ },
24
+ "peerDependencies": {
25
+ "tansy": "^0.1.2"
26
+ }
27
+ }