@snapwonders/report 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,37 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kenneth Springer @ snapWONDERS
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.
22
+
23
+ ---
24
+
25
+ SCOPE OF THIS LICENCE
26
+
27
+ The MIT licence above applies **only** to the source code of this client library
28
+ (the "Software"). It grants no rights in, and says nothing about the licensing of,
29
+ the snapWONDERS API, service, website, data, trained models, or algorithms that
30
+ this library communicates with — all of which are proprietary and remain the
31
+ exclusive property of Kenneth Springer @ snapWONDERS.
32
+
33
+ This library merely displays results returned by the snapWONDERS API; it contains none
34
+ of the API's implementation. Use of the snapWONDERS API requires a valid API key,
35
+ is subject to rate limits and plan tiers, and is governed by the snapWONDERS Terms
36
+ of Service (https://snapwonders.com/terms-of-service). Nothing in the MIT grant above waives
37
+ those terms or confers any right to access the service itself.
package/README.md CHANGED
@@ -1,3 +1,206 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <a href="https://www.snapwonders.com/" target="_blank">
3
+ <img src="https://snapwonders.com/img/logo/snap-wonders-logo-big.png" width="172" alt="snapWONDERS" />
4
+ </a>
5
+ </p>
2
6
 
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.
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.