@proveanything/smartlinks 2.0.4 → 2.0.5
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/dist/docs/API_SUMMARY.md +1 -1
- package/dist/docs/app-manifest.md +15 -0
- package/dist/docs/deploying-apps.md +50 -15
- package/docs/API_SUMMARY.md +1 -1
- package/docs/app-manifest.md +15 -0
- package/docs/deploying-apps.md +50 -15
- package/package.json +1 -1
package/dist/docs/API_SUMMARY.md
CHANGED
|
@@ -147,6 +147,21 @@ The manifest is loaded automatically by the platform for every collection page.
|
|
|
147
147
|
| `platformRevision` | string | ❌ | ISO date string marking the platform API revision this build targets |
|
|
148
148
|
| `seo.priority` | number | ❌ | Controls which app's `title`/`description`/`ogImage` wins when multiple apps are on the same page. Default `0`; higher wins. See the [Executor guide](executor.md). |
|
|
149
149
|
|
|
150
|
+
#### `build`
|
|
151
|
+
|
|
152
|
+
Optional build provenance. Recommended for the **Lovable dev publish** flow: stamp the content
|
|
153
|
+
hash your build already produces here so the platform can tell when a new version is live before it
|
|
154
|
+
registers (see [Deploying & registering](deploying-apps.md#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps)).
|
|
155
|
+
|
|
156
|
+
| Field | Type | Description |
|
|
157
|
+
|-------|------|-------------|
|
|
158
|
+
| `build.hash` | string | Unique build/content hash — the platform waits for this to appear before registering, and uses it as the dev release version |
|
|
159
|
+
| `build.at` | string | ISO timestamp of the build (optional) |
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
"build": { "hash": "a1b2c3d4", "at": "2026-09-20T10:00:00Z" }
|
|
163
|
+
```
|
|
164
|
+
|
|
150
165
|
#### `admin`
|
|
151
166
|
|
|
152
167
|
A relative path (from the app's public root) to the `app.admin.json` file. Omit entirely if the app has no admin UI.
|
|
@@ -16,28 +16,63 @@ This guide covers registration and how to wire it into your build.
|
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
|
19
|
-
## Fast dev publish
|
|
19
|
+
## Fast dev publish
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
Getting a **dev** build live should be instant and secret-free. There are two paths depending on
|
|
22
|
+
**where you build** — pick the one that matches your setup. Both end the same way: the dev release
|
|
23
|
+
is registered and served **`no-store`** (every reload is instantly fresh — no cache-busting, no CDN
|
|
24
|
+
invalidation).
|
|
25
|
+
|
|
26
|
+
### A. From Lovable — hit Publish, no key anywhere *(recommended for Lovable apps)*
|
|
27
|
+
|
|
28
|
+
Lovable builds and hosts your app on **Publish**. You don't push to us and you **don't put any
|
|
29
|
+
secret in Lovable or your repo** — instead your build *pings* us and we pull your just-published
|
|
30
|
+
bundle. Two small additions to your build, both non-secret:
|
|
31
|
+
|
|
32
|
+
1. **Stamp the build hash into `app.manifest.json`.** In the same build step that content-hashes
|
|
33
|
+
your JS, write the hash into the manifest so we can tell when your new version is live:
|
|
34
|
+
```jsonc
|
|
35
|
+
// app.manifest.json
|
|
36
|
+
"build": { "hash": "a1b2c3d4", "at": "2026-09-20T10:00:00Z" }
|
|
37
|
+
```
|
|
38
|
+
2. **Ping us on publish** (a `postbuild` step — `SMARTLINKS_APP_ID` is an *identifier, not a
|
|
39
|
+
secret*, so it's fine in the repo):
|
|
40
|
+
```jsonc
|
|
41
|
+
// package.json
|
|
42
|
+
"scripts": {
|
|
43
|
+
"build": "vite build && … && node scripts/hash-bundles.mjs", // your existing hashing step
|
|
44
|
+
"postbuild": "curl -fsS -X POST \"$SMARTLINKS_API/api/v1/apps/$SMARTLINKS_APP_ID/refresh-dev\" -H 'content-type: application/json' -d \"{\\\"hash\\\":\\\"$BUILD_HASH\\\"}\""
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
That's it — no deploy key. When the ping arrives, SmartLinks looks up your app's published URL
|
|
49
|
+
(from the catalog — **not** from the ping, so it's safe), **waits until your manifest reports that
|
|
50
|
+
exact `build.hash`** (so it never grabs a half-propagated build), validates the manifest + functions,
|
|
51
|
+
and registers the dev release (the hash becomes the version). `POST /apps/{appId}/refresh-dev`
|
|
52
|
+
authorises nothing on its own — worst case it re-fetches your app's own public bundle — so it needs
|
|
53
|
+
no secret; it's rate-limited and de-duped per app.
|
|
54
|
+
|
|
55
|
+
**One-time setup:** the app must exist in the catalog with its **id** and its **Lovable URL**
|
|
56
|
+
recorded (that's how we know what to fetch, and the `id` you ping with must match). Ask the platform
|
|
57
|
+
owner to register the app once; after that, every Publish auto-updates dev.
|
|
58
|
+
|
|
59
|
+
### B. From local / CI / Claude — `smartlinks-publish`
|
|
60
|
+
|
|
61
|
+
If you build somewhere you control (so you can hold a dev key locally — never committed), push the
|
|
62
|
+
built bundle straight to SmartLinks, which hosts + registers it:
|
|
24
63
|
|
|
25
64
|
```bash
|
|
26
|
-
# build
|
|
27
|
-
smartlinks-publish # uploads dist/ → SmartLinks hosts
|
|
65
|
+
# build dist/ first, then:
|
|
66
|
+
smartlinks-publish # uploads dist/ → SmartLinks hosts + registers the dev release
|
|
28
67
|
smartlinks-publish --watch # re-publish on every change (save → live)
|
|
29
68
|
```
|
|
30
69
|
|
|
31
|
-
Env: `SMARTLINKS_APP_ID
|
|
32
|
-
|
|
33
|
-
`
|
|
34
|
-
writes the bundle to `smartlinks.app/apps/{appId}/dev/…` with **`no-store` caching** (every reload
|
|
35
|
-
is instantly fresh — no cache-busting, no invalidation), and registers the release. It works from
|
|
36
|
-
**anywhere** — local, Claude, CI, or a build step — because the builder builds and the platform
|
|
37
|
-
hosts; there's no dependency on any external host for dev.
|
|
70
|
+
Env: `SMARTLINKS_APP_ID`, `SMARTLINKS_DEPLOY_KEY` (dev key — dev-only, safe to keep locally),
|
|
71
|
+
optional `SMARTLINKS_API` / `--dir`. It POSTs the files to `POST /apps/{appId}/publish?channel=dev`;
|
|
72
|
+
the server validates and writes them to `smartlinks.app/apps/{appId}/dev/…` (`no-store`).
|
|
38
73
|
|
|
39
|
-
|
|
40
|
-
|
|
74
|
+
**Which to use:** building in Lovable → **A** (ping, no key). Building anywhere you control →
|
|
75
|
+
**B** (push with a local key). For beta/stable, see the register-a-URL flow below.
|
|
41
76
|
|
|
42
77
|
---
|
|
43
78
|
|
package/docs/API_SUMMARY.md
CHANGED
package/docs/app-manifest.md
CHANGED
|
@@ -147,6 +147,21 @@ The manifest is loaded automatically by the platform for every collection page.
|
|
|
147
147
|
| `platformRevision` | string | ❌ | ISO date string marking the platform API revision this build targets |
|
|
148
148
|
| `seo.priority` | number | ❌ | Controls which app's `title`/`description`/`ogImage` wins when multiple apps are on the same page. Default `0`; higher wins. See the [Executor guide](executor.md). |
|
|
149
149
|
|
|
150
|
+
#### `build`
|
|
151
|
+
|
|
152
|
+
Optional build provenance. Recommended for the **Lovable dev publish** flow: stamp the content
|
|
153
|
+
hash your build already produces here so the platform can tell when a new version is live before it
|
|
154
|
+
registers (see [Deploying & registering](deploying-apps.md#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps)).
|
|
155
|
+
|
|
156
|
+
| Field | Type | Description |
|
|
157
|
+
|-------|------|-------------|
|
|
158
|
+
| `build.hash` | string | Unique build/content hash — the platform waits for this to appear before registering, and uses it as the dev release version |
|
|
159
|
+
| `build.at` | string | ISO timestamp of the build (optional) |
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
"build": { "hash": "a1b2c3d4", "at": "2026-09-20T10:00:00Z" }
|
|
163
|
+
```
|
|
164
|
+
|
|
150
165
|
#### `admin`
|
|
151
166
|
|
|
152
167
|
A relative path (from the app's public root) to the `app.admin.json` file. Omit entirely if the app has no admin UI.
|
package/docs/deploying-apps.md
CHANGED
|
@@ -16,28 +16,63 @@ This guide covers registration and how to wire it into your build.
|
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
|
19
|
-
## Fast dev publish
|
|
19
|
+
## Fast dev publish
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
Getting a **dev** build live should be instant and secret-free. There are two paths depending on
|
|
22
|
+
**where you build** — pick the one that matches your setup. Both end the same way: the dev release
|
|
23
|
+
is registered and served **`no-store`** (every reload is instantly fresh — no cache-busting, no CDN
|
|
24
|
+
invalidation).
|
|
25
|
+
|
|
26
|
+
### A. From Lovable — hit Publish, no key anywhere *(recommended for Lovable apps)*
|
|
27
|
+
|
|
28
|
+
Lovable builds and hosts your app on **Publish**. You don't push to us and you **don't put any
|
|
29
|
+
secret in Lovable or your repo** — instead your build *pings* us and we pull your just-published
|
|
30
|
+
bundle. Two small additions to your build, both non-secret:
|
|
31
|
+
|
|
32
|
+
1. **Stamp the build hash into `app.manifest.json`.** In the same build step that content-hashes
|
|
33
|
+
your JS, write the hash into the manifest so we can tell when your new version is live:
|
|
34
|
+
```jsonc
|
|
35
|
+
// app.manifest.json
|
|
36
|
+
"build": { "hash": "a1b2c3d4", "at": "2026-09-20T10:00:00Z" }
|
|
37
|
+
```
|
|
38
|
+
2. **Ping us on publish** (a `postbuild` step — `SMARTLINKS_APP_ID` is an *identifier, not a
|
|
39
|
+
secret*, so it's fine in the repo):
|
|
40
|
+
```jsonc
|
|
41
|
+
// package.json
|
|
42
|
+
"scripts": {
|
|
43
|
+
"build": "vite build && … && node scripts/hash-bundles.mjs", // your existing hashing step
|
|
44
|
+
"postbuild": "curl -fsS -X POST \"$SMARTLINKS_API/api/v1/apps/$SMARTLINKS_APP_ID/refresh-dev\" -H 'content-type: application/json' -d \"{\\\"hash\\\":\\\"$BUILD_HASH\\\"}\""
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
That's it — no deploy key. When the ping arrives, SmartLinks looks up your app's published URL
|
|
49
|
+
(from the catalog — **not** from the ping, so it's safe), **waits until your manifest reports that
|
|
50
|
+
exact `build.hash`** (so it never grabs a half-propagated build), validates the manifest + functions,
|
|
51
|
+
and registers the dev release (the hash becomes the version). `POST /apps/{appId}/refresh-dev`
|
|
52
|
+
authorises nothing on its own — worst case it re-fetches your app's own public bundle — so it needs
|
|
53
|
+
no secret; it's rate-limited and de-duped per app.
|
|
54
|
+
|
|
55
|
+
**One-time setup:** the app must exist in the catalog with its **id** and its **Lovable URL**
|
|
56
|
+
recorded (that's how we know what to fetch, and the `id` you ping with must match). Ask the platform
|
|
57
|
+
owner to register the app once; after that, every Publish auto-updates dev.
|
|
58
|
+
|
|
59
|
+
### B. From local / CI / Claude — `smartlinks-publish`
|
|
60
|
+
|
|
61
|
+
If you build somewhere you control (so you can hold a dev key locally — never committed), push the
|
|
62
|
+
built bundle straight to SmartLinks, which hosts + registers it:
|
|
24
63
|
|
|
25
64
|
```bash
|
|
26
|
-
# build
|
|
27
|
-
smartlinks-publish # uploads dist/ → SmartLinks hosts
|
|
65
|
+
# build dist/ first, then:
|
|
66
|
+
smartlinks-publish # uploads dist/ → SmartLinks hosts + registers the dev release
|
|
28
67
|
smartlinks-publish --watch # re-publish on every change (save → live)
|
|
29
68
|
```
|
|
30
69
|
|
|
31
|
-
Env: `SMARTLINKS_APP_ID
|
|
32
|
-
|
|
33
|
-
`
|
|
34
|
-
writes the bundle to `smartlinks.app/apps/{appId}/dev/…` with **`no-store` caching** (every reload
|
|
35
|
-
is instantly fresh — no cache-busting, no invalidation), and registers the release. It works from
|
|
36
|
-
**anywhere** — local, Claude, CI, or a build step — because the builder builds and the platform
|
|
37
|
-
hosts; there's no dependency on any external host for dev.
|
|
70
|
+
Env: `SMARTLINKS_APP_ID`, `SMARTLINKS_DEPLOY_KEY` (dev key — dev-only, safe to keep locally),
|
|
71
|
+
optional `SMARTLINKS_API` / `--dir`. It POSTs the files to `POST /apps/{appId}/publish?channel=dev`;
|
|
72
|
+
the server validates and writes them to `smartlinks.app/apps/{appId}/dev/…` (`no-store`).
|
|
38
73
|
|
|
39
|
-
|
|
40
|
-
|
|
74
|
+
**Which to use:** building in Lovable → **A** (ping, no key). Building anywhere you control →
|
|
75
|
+
**B** (push with a local key). For beta/stable, see the register-a-URL flow below.
|
|
41
76
|
|
|
42
77
|
---
|
|
43
78
|
|