diff --git a/src/pages/sdk/connect-quickstart/index.astro b/src/pages/sdk/connect-quickstart/index.astro index 7d220c1..d92cbe2 100644 --- a/src/pages/sdk/connect-quickstart/index.astro +++ b/src/pages/sdk/connect-quickstart/index.astro @@ -64,6 +64,12 @@ pnpm package:consumer -- \\ --destination ../workouts-app/vendor \\ --packages connect,protocol`; +const localStack = `# Run in the mdbase-connect checkout. +pnpm dev:environment:up + +# Run in another terminal. +pnpm dev:desktop:fresh`; + const validate = `mdbase-connect-dev validate-manifest \\ public/.well-known/mdbase-app.json \\ --allow-local`; @@ -79,8 +85,16 @@ export interface Workout extends JsonObject { completed?: boolean; } +const loopback = new Set([ + "localhost", + "127.0.0.1", + "::1" +]).has(location.hostname); + export const mdbase = new MdbaseConnect({ - serverUrl: "https://connect.mdbase.dev", + serverUrl: loopback + ? "http://127.0.0.1:8787" + : "https://connect.mdbase.dev", manifest: new URL( "/.well-known/mdbase-app.json", location.origin @@ -177,27 +191,40 @@ if (first) { { href: "#authorize", label: "4. Authorize" }, { href: "#callback", label: "5. Complete callback" }, { href: "#operate", label: "6. Use operations" }, + { href: "#production", label: "Production HTTPS" }, { href: "#success", label: "Expected result" } ]} >
- Private-beta path + Local and managed Connect are separate environments.

- The production service currently accepts private-beta accounts. The - public SDK packages are also awaiting their first npm release. Start with - the local sandbox guide if you do not have - beta access. + This guide's localhost example uses the repository's local Connect stack. + The managed service rejects HTTP application manifests, including + localhost. To use https://connect.mdbase.dev, deploy the + application at HTTPS URLs and declare those exact URLs in its manifest.

Before you begin

This guide expects:

+

+ In the Connect checkout, copy .env.example to .env + {" "}on first use, then start the local control plane and an isolated desktop + profile: +

+ +

+ Enter http://127.0.0.1:8787 in the desktop pairing screen, + approve the computer in the local portal, and add a collection. This profile + is separate from the normal desktop profile: accounts, grants, and + collections registered with the managed service do not appear automatically. +

The example manifest carries a complete transactional contract/type pack. Connect can install it during approval when the chosen collection does not @@ -207,9 +234,9 @@ if (first) {

1. Add a bundled application manifest

Save this file at - {" "}public/.well-known/mdbase-app.json. The local URLs are valid - for development and require the validator's - {" "}--allow-local option. + {" "}public/.well-known/mdbase-app.json. These loopback URLs are + accepted by the local Connect stack. Pass --allow-local to the + validator when checking this development manifest.

@@ -230,9 +257,11 @@ if (first) {

The validator is currently run from the Connect workspace or supplied as a - beta artifact: + beta artifact. --allow-local affects static validation only; it + is not an option on the desktop application and does not change the managed + service's HTTPS policy:

- +

3. Create one stable Connect client

@@ -272,6 +301,21 @@ if (first) { those normalized values to the application.

+

Move to the managed service

+

+ The production service currently accepts private-beta accounts. Before using + it, deploy the application at an HTTPS origin, replace every localhost + homepage, icon, and redirect URL in the manifest with the exact deployed + URLs, and validate without --allow-local. The non-loopback branch + in the client example then uses https://connect.mdbase.dev. +

+

+ A localhost application cannot connect to the managed service. Use the full + local environment above for local protocol testing, or use the + {" "}in-memory sandbox for feature tests that + do not need authorization, routing, or a real connector. +

+

What success looks like

  1. The Connect approval screen names Example Workouts.