@snapwonders/report 0.2.1 → 0.3.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/README.md CHANGED
@@ -1,206 +1,206 @@
1
- <p align="center">
2
- <a href="https://www.snapwonders.com/" target="_blank">
3
- <img src="https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-Report/main/.github/social-preview.jpg" alt="snapWONDERS Report" width="640" />
4
- </a>
5
- </p>
6
-
7
- snapWONDERS — Expose what's hidden. Hide what's yours.
8
-
9
-
10
- # snapWONDERS Report — draw an analysis result in one tag
11
-
12
- The snapWONDERS API returns a rich forensic result for every photo or video: two headline grades,
13
- how sure we are, what the AI-generation check found, Content Credentials, faces, readable text and
14
- the key findings. **This package draws that result for you**, the same way the snapWONDERS report
15
- page does, so you can show it to your users without writing any presentation code.
16
-
17
- * One dependency-free web component, `<snapwonders-report>`. No framework, no build step.
18
- * Two modes: a compact **card**, and a **full** report with every public check and the analysis
19
- images.
20
- * Works anywhere a browser does: your web app, a browser extension, a WordPress page.
21
- * It reads only the public result the API already returns, writes every value as text (never as
22
- HTML), and makes **no network calls of its own**.
23
- * MIT, so restyle it, extend it or white-label it however your product needs.
24
-
25
- All the snapWONDERS API services are available over the Clearnet / **Web** and Dark Web **Tor** and
26
- **I2P**. Read details: https://snapwonders.com/developers
27
-
28
-
29
- # See it in action
30
-
31
- <p align="center"><img src="https://snapwonders.com/images/report-examples/ai-generated/card.png" width="544" alt="A snapWONDERS result card for an AI-generated café photo: Authenticity C, moderate risk; Exposure B, low risk; processed by an AI image generator, 3 faces, 14 text areas" /></p>
32
-
33
- We asked an AI image generator for a café photo with two people and readable signs, then checked it
34
- with the snapWONDERS API. The card above is this package drawing the unchanged JSON from
35
- `GET /api/analyse/result/{job_uid}`.
36
-
37
- The same result in **full** mode, with the reasons and the evidence maps:
38
- [open the full report](https://snapwonders.com/images/report-examples/ai-generated/full.png).
39
-
40
- More examples, all hosted on snapwonders.com:
41
-
42
- * [Example reports](https://snapwonders.com/products/examples): an AI-generated photo, an edited
43
- photo and a camera original, with what each report tells you.
44
- * [Developer examples](https://snapwonders.com/developers/examples): the JSON behind each report and
45
- how to draw it.
46
-
47
-
48
- # Installation and setup
49
-
50
- ## snapWONDERS API key
51
- You will need a snapWONDERS API key to fetch results:
52
-
53
- * Sign up and create an account at [snapWONDERS sign-up](https://snapwonders.com/signup). If you
54
- wish to create an account via Tor or I2P then you can do so by accessing snapWONDERS through the
55
- Tor or I2P portals. For the dark web links visit
56
- [browsing safely](https://snapwonders.com/browsing-safely).
57
- * Under your account settings, generate an API key. New keys start with `sw_`. It is sent as the
58
- `X-Api-Key` header on every request — keep it secret, and **never put it in browser code**. Fetch
59
- the result on your server and pass the JSON to the page.
60
-
61
- ## Install the package
62
-
63
- ```bash
64
- npm install @snapwonders/report
65
- ```
66
-
67
- Or copy the `src/` folder into your project — it has no dependencies. Browser extensions and
68
- WordPress plugins must bundle it this way: their stores do not allow loading code from another
69
- server.
70
-
71
-
72
- # Quickstart
73
-
74
- ```html
75
- <snapwonders-report id="card" report-url="https://snapwonders.com/upload/analyse/result/…" check-another></snapwonders-report>
76
-
77
- <script type="module">
78
- import '@snapwonders/report';
79
-
80
- // `result` is the JSON your server got from GET /api/analyse/result/{job_uid}
81
- document.getElementById('card').result = result;
82
- </script>
83
- ```
84
-
85
- On a static page you can put the result inline instead:
86
-
87
- ```html
88
- <snapwonders-report>
89
- <script type="application/json">{ "schema_version": "1.0", "files": [ … ] }</script>
90
- </snapwonders-report>
91
- ```
92
-
93
- | Attribute | What it does |
94
- |---|---|
95
- | `mode` | `card` (default) or `full` |
96
- | `report-url` | Adds an **Open full report** button linking to that address |
97
- | `check-another` | Adds a **Check another** button; listen for the `snapwonders-check-another` event |
98
- | `file-index` | Which file of a multi-file result to draw (default `0`) |
99
- | `link-params` | Tracking parameters added to the snapWONDERS links, e.g. `src=myapp` (keys `src`, `site`, `r`) |
100
-
101
- **Full report with your analysis images.** The API returns each analysis image as an asset with a
102
- `download_path` that needs your API key, so download them on your server and tell the renderer where
103
- you keep them:
104
-
105
- ```js
106
- const report = document.querySelector('snapwonders-report[mode="full"]');
107
- report.assetUrl = (asset) => `/media/snapwonders/${asset.asset_id}.jpg`; // your copy of each image
108
- report.result = result;
109
- ```
110
-
111
- **Attribution.** The "Checked by snapWONDERS" credit and the snapWONDERS Vaultify link are part of
112
- the API result (`attribution`, `vaultify_cta`). The renderer draws them only when they point at
113
- snapwonders.com and never adds a credit of its own.
114
-
115
- **One file.** `npm run build` writes `dist/snapwonders-report.js`, the whole renderer as a single
116
- classic script. Browser extensions and WordPress plugins bundle that file: their stores do not allow
117
- loading code from another server.
118
-
119
- **Theming.** Set any of `--sw-font`, `--sw-bg`, `--sw-text`, `--sw-muted`, `--sw-border`,
120
- `--sw-accent` and `--sw-radius` on the element.
121
-
122
- **Without the element.** `import { buildCardModel } from '@snapwonders/report/model'` gives you the
123
- same wording as plain data, for a native app or server-side rendering.
124
-
125
-
126
- # Keeping up with the API
127
-
128
- Every result carries `schema_version` (`major.minor`); this version knows up to **1.4**
129
- (`SUPPORTED_SCHEMA`). When a result is newer, by any bump, minor too, the card still draws everything it
130
- understands, adds a small note *"A new version is available, with more in this report. See what's new"*,
131
- and fires `snapwonders-update-available` so your app can prompt an update. The note is gentle for a
132
- minor bump and firmer for a major one (*"Update needed: …"*). It has a × button: the element then fires
133
- `snapwonders-update-dismissed` with the result's `schemaVersion`; keep that (an extension keeps it in its
134
- storage) and pass it back as `dismissed-update`, and the note stays hidden for that version and returns on
135
- the next. The result's `schema_version` is separate from your product's version: a big extension
136
- release does not change it. Set `release-notes-url` to
137
- your own release notes (an extension or plugin version page); without it the note links to this
138
- package's changelog. A field that is missing, `null` or of the wrong type is simply not drawn: the
139
- renderer never fails on a result, and a test feeds it thousands of damaged results to keep it that way.
140
-
141
-
142
- # Running the tests
143
-
144
- ```bash
145
- npm test
146
- ```
147
-
148
- The tests run offline on Node 18 or later and need no API key.
149
-
150
-
151
- # Documentation
152
-
153
- Useful documentation can be found at:
154
-
155
- * The interactive Swagger UI and full endpoint reference:
156
- [snapWONDERS API](https://snapwonders.com/api)
157
- * A guided, step-by-step integration walkthrough:
158
- [snapWONDERS Developers](https://snapwonders.com/developers)
159
-
160
-
161
- # Contact
162
-
163
- ## For security concerns
164
- If you have spotted any security concerns then please reach out via
165
- [contacting snapWONDERS](https://snapwonders.com/contact) and set the subject to
166
- **"SECURITY CONCERNS"** and provide the information about your concerns. If you wish to contact via
167
- Tor or I2P then you can do so by accessing snapWONDERS through the Tor or I2P portals. For the dark
168
- web links visit [browsing safely](https://snapwonders.com/browsing-safely).
169
-
170
- ## For FAQ and questions
171
- It may be that your question is already answered in the [FAQ](https://snapwonders.com/faq). Be sure
172
- to check the FAQ content first. Otherwise you may reach out via
173
- [contacting snapWONDERS](https://snapwonders.com/contact).
174
-
175
- ## For contacting the author
176
- Use this link to contact the author [Kenneth Springer](https://kennethbspringer.au/).
177
-
178
-
179
- # Why snapWONDERS exists
180
-
181
- This project started with my son, Huey.
182
-
183
- Huey lost his eyesight and was legally blind from the age of four. Years ago, in the car, while we were working on Hueyify together, he insisted the idea could be applied to digital media: stories embedded inside a photo, so that people with vision impairments could get the personal context, the memory and the feeling behind it. Hidden from everyone else. Only for the person it was meant for.
184
-
185
- He was excited at the thought of it. I'll admit the technical difficulty put me off, and I was vocal about it. The look of disappointment kept returning to me, because to Huey it all made sense. We lost Huey at sixteen. I could never let go of that conversation.
186
-
187
- snapWONDERS came first, to understand what digital media actually contains and who can see it. Vaultify came after, and it is the closest thing I've built to what Huey described. As of September 2026, snapWONDERS and Vaultify have processed more than six million media jobs.
188
-
189
- The full story is at https://vaultify.snapwonders.com/our-story
190
-
191
- May peace be with you,<br>
192
- Kenneth Springer
193
-
194
-
195
- # Licence
196
-
197
- MIT — Copyright (c) 2026 Kenneth Springer @ snapWONDERS. See [LICENSE](LICENSE).
198
-
199
- **Scope.** The MIT licence covers **this library only**. It grants no rights in the snapWONDERS API,
200
- service, data, models, or algorithms whose results it displays — these are **proprietary** and remain
201
- the property of Kenneth Springer @ snapWONDERS. Use of the API requires an API key and is governed by
202
- the [snapWONDERS Terms of Service](https://snapwonders.com/terms-of-service).
203
-
204
- The MIT licence also does not cover the snapwonders.com website or anything it hosts (including the
205
- example photos, results and report images), or the snapWONDERS and Vaultify names and logos —
206
- © Kenneth Springer @ snapWONDERS, all rights reserved.
1
+ <p align="center">
2
+ <a href="https://www.snapwonders.com/" target="_blank">
3
+ <img src="https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-Report/main/.github/social-preview.jpg" alt="snapWONDERS Report" width="640" />
4
+ </a>
5
+ </p>
6
+
7
+ snapWONDERS — Expose what's hidden. Hide what's yours.
8
+
9
+
10
+ # snapWONDERS Report — draw an analysis result in one tag
11
+
12
+ The snapWONDERS API returns a rich forensic result for every photo or video: two headline grades,
13
+ how sure we are, what the AI-generation check found, Content Credentials, faces, readable text and
14
+ the key findings. **This package draws that result for you**, the same way the snapWONDERS report
15
+ page does, so you can show it to your users without writing any presentation code.
16
+
17
+ * One dependency-free web component, `<snapwonders-report>`. No framework, no build step.
18
+ * Two modes: a compact **card**, and a **full** report with every public check and the analysis
19
+ images.
20
+ * Works anywhere a browser does: your web app, a browser extension, a WordPress page.
21
+ * It reads only the public result the API already returns, writes every value as text (never as
22
+ HTML), and makes **no network calls of its own**.
23
+ * MIT, so restyle it, extend it or white-label it however your product needs.
24
+
25
+ All the snapWONDERS API services are available over the Clearnet / **Web** and Dark Web **Tor** and
26
+ **I2P**. Read details: https://snapwonders.com/developers
27
+
28
+
29
+ # See it in action
30
+
31
+ <p align="center"><img src="https://snapwonders.com/images/report-examples/ai-generated/card.png" width="544" alt="A snapWONDERS result card for an AI-generated café photo: Authenticity C, moderate risk; Exposure B, low risk; processed by an AI image generator, 3 faces, 14 text areas" /></p>
32
+
33
+ We asked an AI image generator for a café photo with two people and readable signs, then checked it
34
+ with the snapWONDERS API. The card above is this package drawing the unchanged JSON from
35
+ `GET /api/analyse/result/{job_uid}`.
36
+
37
+ The same result in **full** mode, with the reasons and the evidence maps:
38
+ [open the full report](https://snapwonders.com/images/report-examples/ai-generated/full.png).
39
+
40
+ More examples, all hosted on snapwonders.com:
41
+
42
+ * [Example reports](https://snapwonders.com/products/examples): an AI-generated photo, an edited
43
+ photo and a camera original, with what each report tells you.
44
+ * [Developer examples](https://snapwonders.com/developers/examples): the JSON behind each report and
45
+ how to draw it.
46
+
47
+
48
+ # Installation and setup
49
+
50
+ ## snapWONDERS API key
51
+ You will need a snapWONDERS API key to fetch results:
52
+
53
+ * Sign up and create an account at [snapWONDERS sign-up](https://snapwonders.com/signup). If you
54
+ wish to create an account via Tor or I2P then you can do so by accessing snapWONDERS through the
55
+ Tor or I2P portals. For the dark web links visit
56
+ [browsing safely](https://snapwonders.com/browsing-safely).
57
+ * Under your account settings, generate an API key. New keys start with `sw_`. It is sent as the
58
+ `X-Api-Key` header on every request — keep it secret, and **never put it in browser code**. Fetch
59
+ the result on your server and pass the JSON to the page.
60
+
61
+ ## Install the package
62
+
63
+ ```bash
64
+ npm install @snapwonders/report
65
+ ```
66
+
67
+ Or copy the `src/` folder into your project — it has no dependencies. Browser extensions and
68
+ WordPress plugins must bundle it this way: their stores do not allow loading code from another
69
+ server.
70
+
71
+
72
+ # Quickstart
73
+
74
+ ```html
75
+ <snapwonders-report id="card" report-url="https://snapwonders.com/upload/analyse/result/…" check-another></snapwonders-report>
76
+
77
+ <script type="module">
78
+ import '@snapwonders/report';
79
+
80
+ // `result` is the JSON your server got from GET /api/analyse/result/{job_uid}
81
+ document.getElementById('card').result = result;
82
+ </script>
83
+ ```
84
+
85
+ On a static page you can put the result inline instead:
86
+
87
+ ```html
88
+ <snapwonders-report>
89
+ <script type="application/json">{ "schema_version": "1.0", "files": [ … ] }</script>
90
+ </snapwonders-report>
91
+ ```
92
+
93
+ | Attribute | What it does |
94
+ |---|---|
95
+ | `mode` | `card` (default) or `full` |
96
+ | `report-url` | Adds an **Open full report** button linking to that address. Without it, the button uses the result's own `report_url` when there is one (schema 1.5) |
97
+ | `check-another` | Adds a **Check another** button; listen for the `snapwonders-check-another` event |
98
+ | `file-index` | Which file of a multi-file result to draw (default `0`) |
99
+ | `link-params` | Tracking parameters added to the snapWONDERS links, e.g. `src=myapp` (keys `src`, `site`, `r`) |
100
+
101
+ **Full report with your analysis images.** The API returns each analysis image as an asset with a
102
+ `download_path` that needs your API key, so download them on your server and tell the renderer where
103
+ you keep them:
104
+
105
+ ```js
106
+ const report = document.querySelector('snapwonders-report[mode="full"]');
107
+ report.assetUrl = (asset) => `/media/snapwonders/${asset.asset_id}.jpg`; // your copy of each image
108
+ report.result = result;
109
+ ```
110
+
111
+ **Attribution.** The "Checked by snapWONDERS" credit and the snapWONDERS Vaultify link are part of
112
+ the API result (`attribution`, `vaultify_cta`). The renderer draws them only when they point at
113
+ snapwonders.com and never adds a credit of its own.
114
+
115
+ **One file.** `npm run build` writes `dist/snapwonders-report.js`, the whole renderer as a single
116
+ classic script. Browser extensions and WordPress plugins bundle that file: their stores do not allow
117
+ loading code from another server.
118
+
119
+ **Theming.** Set any of `--sw-font`, `--sw-bg`, `--sw-text`, `--sw-muted`, `--sw-border`,
120
+ `--sw-accent` and `--sw-radius` on the element.
121
+
122
+ **Without the element.** `import { buildCardModel } from '@snapwonders/report/model'` gives you the
123
+ same wording as plain data, for a native app or server-side rendering.
124
+
125
+
126
+ # Keeping up with the API
127
+
128
+ Every result carries `schema_version` (`major.minor`); this version knows up to **1.5**
129
+ (`SUPPORTED_SCHEMA`). When a result is newer, by any bump, minor too, the card still draws everything it
130
+ understands, adds a small note *"A new version is available, with more in this report. See what's new"*,
131
+ and fires `snapwonders-update-available` so your app can prompt an update. The note is gentle for a
132
+ minor bump and firmer for a major one (*"Update needed: …"*). It has a × button: the element then fires
133
+ `snapwonders-update-dismissed` with the result's `schemaVersion`; keep that (an extension keeps it in its
134
+ storage) and pass it back as `dismissed-update`, and the note stays hidden for that version and returns on
135
+ the next. The result's `schema_version` is separate from your product's version: a big extension
136
+ release does not change it. Set `release-notes-url` to
137
+ your own release notes (an extension or plugin version page); without it the note links to this
138
+ package's changelog. A field that is missing, `null` or of the wrong type is simply not drawn: the
139
+ renderer never fails on a result, and a test feeds it thousands of damaged results to keep it that way.
140
+
141
+
142
+ # Running the tests
143
+
144
+ ```bash
145
+ npm test
146
+ ```
147
+
148
+ The tests run offline on Node 18 or later and need no API key.
149
+
150
+
151
+ # Documentation
152
+
153
+ Useful documentation can be found at:
154
+
155
+ * The interactive Swagger UI and full endpoint reference:
156
+ [snapWONDERS API](https://snapwonders.com/api)
157
+ * A guided, step-by-step integration walkthrough:
158
+ [snapWONDERS Developers](https://snapwonders.com/developers)
159
+
160
+
161
+ # Contact
162
+
163
+ ## For security concerns
164
+ If you have spotted any security concerns then please reach out via
165
+ [contacting snapWONDERS](https://snapwonders.com/contact) and set the subject to
166
+ **"SECURITY CONCERNS"** and provide the information about your concerns. If you wish to contact via
167
+ Tor or I2P then you can do so by accessing snapWONDERS through the Tor or I2P portals. For the dark
168
+ web links visit [browsing safely](https://snapwonders.com/browsing-safely).
169
+
170
+ ## For FAQ and questions
171
+ It may be that your question is already answered in the [FAQ](https://snapwonders.com/faq). Be sure
172
+ to check the FAQ content first. Otherwise you may reach out via
173
+ [contacting snapWONDERS](https://snapwonders.com/contact).
174
+
175
+ ## For contacting the author
176
+ Use this link to contact the author [Kenneth Springer](https://kennethbspringer.au/).
177
+
178
+
179
+ # Why snapWONDERS exists
180
+
181
+ This project started with my son, Huey.
182
+
183
+ Huey lost his eyesight and was legally blind from the age of four. Years ago, in the car, while we were working on Hueyify together, he insisted the idea could be applied to digital media: stories embedded inside a photo, so that people with vision impairments could get the personal context, the memory and the feeling behind it. Hidden from everyone else. Only for the person it was meant for.
184
+
185
+ He was excited at the thought of it. I'll admit the technical difficulty put me off, and I was vocal about it. The look of disappointment kept returning to me, because to Huey it all made sense. We lost Huey at sixteen. I could never let go of that conversation.
186
+
187
+ snapWONDERS came first, to understand what digital media actually contains and who can see it. Vaultify came after, and it is the closest thing I've built to what Huey described. As of September 2026, snapWONDERS and Vaultify have processed more than six million media jobs.
188
+
189
+ The full story is at https://vaultify.snapwonders.com/our-story
190
+
191
+ May peace be with you,<br>
192
+ Kenneth Springer
193
+
194
+
195
+ # Licence
196
+
197
+ MIT — Copyright (c) 2026 Kenneth Springer @ snapWONDERS. See [LICENSE](LICENSE).
198
+
199
+ **Scope.** The MIT licence covers **this library only**. It grants no rights in the snapWONDERS API,
200
+ service, data, models, or algorithms whose results it displays — these are **proprietary** and remain
201
+ the property of Kenneth Springer @ snapWONDERS. Use of the API requires an API key and is governed by
202
+ the [snapWONDERS Terms of Service](https://snapwonders.com/terms-of-service).
203
+
204
+ The MIT licence also does not cover the snapwonders.com website or anything it hosts (including the
205
+ example photos, results and report images), or the snapWONDERS and Vaultify names and logos —
206
+ © Kenneth Springer @ snapWONDERS, all rights reserved.