@garagem-ai/site-sdk 0.4.1 → 0.4.3

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
@@ -64,6 +64,11 @@ raw escape hatch when you need full control.
64
64
  | `getCmsCollection({ siteId, slug })` | One CMS collection schema |
65
65
  | `getCmsEntries({ siteId, collection, limit?, offset? })` | Published CMS entries only |
66
66
  | `getCmsEntry({ siteId, collection, slug })` | One published CMS entry |
67
+ | `getSearchUi({ siteId, next? })` | Tenant search schema (filters, slugs) |
68
+ | `getLeadUi({ siteId, next? })` | Visit-default lead dialog schema (weekday hours, Sat/Sun flags) |
69
+ | `submitVisitLead({ siteId, listingId, … })` | POST a visit lead (`listing.id` UUID, `visitDate` + `visitTime`) |
70
+ | `submitContactLead({ siteId, listingId, … })` | POST a contact lead (no date/time) |
71
+ | `slotsForDate` / `expandVisitSchedule` | Pure schedule helpers (`America/Sao_Paulo`, default Mon–Fri 06:00–22:00) |
67
72
  | `resolvePublicSiteId({ host?, fallback? })` | Preview uses `fallback` (`GARAGEM_SITE_ID`); live hosts resolve via `getSite({ domain })` |
68
73
 
69
74
  ### Advanced layer (when the friendly one isn't enough)
@@ -245,35 +250,26 @@ option on `createGaragemClient`.
245
250
 
246
251
  Headless URL/search helpers live on the main entry (`readPublicSearch`,
247
252
  `hrefForPathFilters`, `toListingCardModel`, …). The React adapter is a
248
- separate subpath — peer `react` + `next`:
253
+ separate subpath — peer `react` + `next`.
249
254
 
250
- ```tsx
251
- import { SearchChromeStyles } from "@garagem-ai/site-sdk/react";
255
+ Studio codegen follows `STUDIO_SDK_CONTRACT`: pin
256
+ `@garagem-ai/site-sdk` to `minNpmVersion` and import only
257
+ `reactExports` (`SearchPage`, `ListingCard`, `usePublicSearch`,
258
+ `ResultsSkeleton` on the Studio pin). Preview, open-in-new-tab, and
259
+ published `next build` all resolve that tarball. Do **not** import npm
260
+ CSS (`@garagem-ai/site-sdk/react/search.css`) in Studio.
252
261
 
253
- export default function RootLayout({
254
- children,
255
- }: {
256
- children: React.ReactNode;
257
- }) {
258
- return (
259
- <html lang="pt-BR">
260
- <body>
261
- <SearchChromeStyles />
262
- {children}
263
- </body>
264
- </html>
265
- );
266
- }
267
- ```
262
+ `SearchPage`, `ListingCard`, and `ResultsSkeleton` inject the chrome
263
+ stylesheet (JS `<style>` tag). Layout tags are optional.
268
264
 
269
265
  ```tsx
270
266
  "use client";
271
267
  import { Suspense } from "react";
272
- import { SearchPage, SearchPageFallback } from "@garagem-ai/site-sdk/react";
268
+ import { SearchPage, ResultsSkeleton } from "@garagem-ai/site-sdk/react";
273
269
 
274
270
  export default function ImoveisPage() {
275
271
  return (
276
- <Suspense fallback={<SearchPageFallback />}>
272
+ <Suspense fallback={<ResultsSkeleton />}>
277
273
  <SearchPage
278
274
  siteId={process.env.NEXT_PUBLIC_GARAGEM_SITE_ID!}
279
275
  variant="toolbar"
@@ -283,20 +279,16 @@ export default function ImoveisPage() {
283
279
  }
284
280
  ```
285
281
 
286
- `variant` is `toolbar` (default), `dialog`, or `sidebar`. Studio and v0
287
- preview must use `SearchChromeStyles` (a JS module that emits a `<style>`
288
- tag). Do not `import "@garagem-ai/site-sdk/react/search.css"` in generated
289
- Studio apps — the preview ESM CDN cannot load npm CSS. That file export
290
- remains for plain Next consumers who prefer a CSS import.
291
-
292
- `SearchPage` and `SearchPageFallback` also emit the sheet if the layout
293
- omits `SearchChromeStyles`. Home listing cards still need the layout tag
294
- (or a parent that renders it). Customize with CSS variables
295
- (`SEARCH_CSS_VARS` / `SEARCH_CSS_RECIPE` in `globals.css`), `classNames`,
296
- `icons`, and `data-slot`. Home and search should share `ListingCard`.
297
- The search H1 is SEO stable: hit count is a sibling `<span>`, not inside
298
- `<h1>`. Presentation tokens stay framework-free on the main entry so
299
- other adapters can reuse them.
282
+ `variant` is `toolbar` (default), `dialog`, or `sidebar`. Customize with
283
+ CSS variables (`SEARCH_CSS_VARS` / `SEARCH_CSS_RECIPE` in `globals.css`),
284
+ `classNames`, `icons`, and `data-slot`. Home and search should share
285
+ `ListingCard`. The search H1 is SEO stable: hit count is a sibling
286
+ `<span>`, not inside `<h1>`. Presentation tokens stay framework-free on
287
+ the main entry so other adapters can reuse them.
288
+
289
+ Hand-written Next apps that prefer a layout tag or a padded search
290
+ fallback can import those after they ship on npm; until then they are
291
+ not part of the Studio pin.
300
292
 
301
293
  ## What's NOT in this release
302
294
 
package/dist/index.d.mts CHANGED
@@ -147,6 +147,114 @@ declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntrie
147
147
  /** Fetch one published CMS entry by slug. */
148
148
  declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
149
149
 
150
+ /**
151
+ * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
152
+ * Calendar dates are civil dates in `timeZone` (America/Sao_Paulo), never
153
+ * UTC midnight from `new Date("YYYY-MM-DD")`.
154
+ */
155
+ declare const VISIT_TIME_ZONE: "America/Sao_Paulo";
156
+ type HHmm = string;
157
+ type VisitHours = {
158
+ start: HHmm;
159
+ end: HHmm;
160
+ };
161
+ type VisitScheduleConfig = {
162
+ timeZone: typeof VISIT_TIME_ZONE;
163
+ saturday: boolean;
164
+ sunday: boolean;
165
+ weekday: VisitHours;
166
+ weekend: VisitHours | null;
167
+ minHoursAhead: number;
168
+ };
169
+ type VisitSchedule = VisitScheduleConfig & {
170
+ disabledDays: number[];
171
+ weekdayTimeSlots: HHmm[];
172
+ weekendTimeSlots: HHmm[];
173
+ timeSlots: HHmm[];
174
+ };
175
+ declare function expandVisitTimeSlots(hours: VisitHours): HHmm[];
176
+ declare function expandVisitSchedule(config: VisitScheduleConfig): VisitSchedule;
177
+ declare const STUDIO_DEFAULT_VISIT_SCHEDULE: VisitSchedule;
178
+ declare function slotsForDate(schedule: VisitSchedule, date: Date | string, now?: Date): HHmm[];
179
+ declare function isVisitSlotAllowed(schedule: VisitSchedule, visitDate: string, visitTime: HHmm, now?: Date): boolean;
180
+
181
+ /**
182
+ * Headless visit / contact leads. Schema via GET /leads/ui; POST always
183
+ * goes to the webhook (`source: "site-sdk"`). v0 draws the dialog.
184
+ */
185
+
186
+ type LeadFieldId = "name" | "email" | "phone" | "message";
187
+ type LeadField = {
188
+ id: LeadFieldId;
189
+ required: boolean;
190
+ };
191
+ type LeadUi = {
192
+ defaultVariant: "visit";
193
+ timeZone: "America/Sao_Paulo";
194
+ variants: {
195
+ visit: {
196
+ ctaLabel: string;
197
+ requireDateTime: true;
198
+ schedule: VisitSchedule;
199
+ fields: LeadField[];
200
+ };
201
+ contact: {
202
+ ctaLabel: string;
203
+ requireDateTime: false;
204
+ whatsappPhone: string | null;
205
+ fields: LeadField[];
206
+ };
207
+ };
208
+ };
209
+ type GetLeadUiOptions = {
210
+ siteId: string;
211
+ baseUrl?: string;
212
+ fetch?: FetchLike;
213
+ next?: RequestNextOptions;
214
+ };
215
+ type LeadContact = {
216
+ name: string;
217
+ email?: string;
218
+ phone?: string;
219
+ message?: string;
220
+ };
221
+ type LeadSubmitBase = LeadContact & {
222
+ siteId: string;
223
+ baseUrl?: string;
224
+ fetch?: FetchLike;
225
+ listingId: string;
226
+ visitorId?: string;
227
+ brokerRef?: string;
228
+ referrer?: string;
229
+ };
230
+ type VisitLeadInput = LeadSubmitBase & {
231
+ visitDate: string;
232
+ visitTime: HHmm;
233
+ schedule?: VisitSchedule;
234
+ };
235
+ type ContactLeadInput = LeadSubmitBase;
236
+ type LeadSubmitResult = {
237
+ ok: true;
238
+ status: 202;
239
+ id: string;
240
+ };
241
+ type LeadSubmitErrorCode = "invalid_listing_id" | "invalid_contact" | "invalid_slot" | "rate_limited" | "not_found" | "http" | "network";
242
+ declare class LeadSubmitError extends Error {
243
+ readonly code: LeadSubmitErrorCode;
244
+ readonly status?: number;
245
+ readonly retryAfterSeconds?: number;
246
+ constructor(message: string, info: {
247
+ code: LeadSubmitErrorCode;
248
+ status?: number;
249
+ retryAfterSeconds?: number;
250
+ });
251
+ }
252
+ /** Fallback when GET /leads/ui fails — same default the API publishes. */
253
+ declare function studioDefaultLeadUi(): LeadUi;
254
+ declare function getLeadUi(options: GetLeadUiOptions): Promise<LeadUi>;
255
+ declare function submitVisitLead(input: VisitLeadInput): Promise<LeadSubmitResult>;
256
+ declare function submitContactLead(input: ContactLeadInput): Promise<LeadSubmitResult>;
257
+
150
258
  /** Public listing URLs. Prefer `listing.path` from the API; fallback is `/imoveis/id-{listingCode}`. */
151
259
  declare function listingLookupKey(raw: string): string;
152
260
  declare function listingPublicPath(listing: {
@@ -232,6 +340,60 @@ declare function isStudioPreviewHost(host: string): boolean;
232
340
  */
233
341
  declare function resolvePublicSiteId(options: ResolvePublicSiteIdOptions): Promise<string>;
234
342
 
343
+ /**
344
+ * Studio ↔ npm contract. Prompt, completeness, and recipes must read this
345
+ * object — do not keep a second list of required `@garagem-ai/site-sdk/react`
346
+ * names in apps/site.
347
+ *
348
+ * `minNpmVersion` is the tarball v0 actually installs. Optional exports exist
349
+ * in git and may already be on npm, but Studio codegen must not name them
350
+ * while chromeStrategy is self-inject (v0 copies identifiers; a layout tag
351
+ * also breaks the pancake stack).
352
+ */
353
+ declare const STUDIO_SDK_PACKAGE: "@garagem-ai/site-sdk";
354
+ declare const STUDIO_SDK_CONTRACT: {
355
+ readonly package: "@garagem-ai/site-sdk";
356
+ /**
357
+ * Exact pin for generated Studio sites. Must be ≥ `selfInjectSince` so
358
+ * prompts that skip the layout chrome tag match the tarball v0 installs.
359
+ * This PR’s changeset publishes that tarball as 0.4.3 — do not generate
360
+ * against this floor until Version Packages is on npm.
361
+ */
362
+ readonly minNpmVersion: "0.4.3";
363
+ /** First release where ListingCard and ResultsSkeleton inject the sheet. */
364
+ readonly selfInjectSince: "0.4.2";
365
+ readonly chromeStrategy: "self-inject";
366
+ readonly reactExports: readonly ["SearchPage", "ListingCard", "usePublicSearch", "ResultsSkeleton"];
367
+ /**
368
+ * Names that exist in git / the unpublished patch. Completeness treats an
369
+ * import as `sdk-export-mismatch` when the generated pin is older than
370
+ * `since`. Studio prompts must not mention these names at all (even as
371
+ * “never import”) — v0 copies the identifier and the preview ESM loader
372
+ * throws FatalRendererError.
373
+ */
374
+ readonly optionalReactExports: {
375
+ readonly SearchPageFallback: "0.4.1";
376
+ readonly SearchChromeStyles: "0.4.1";
377
+ };
378
+ readonly forbiddenImports: readonly ["@garagem-ai/site-sdk/react/search.css"];
379
+ readonly leadStrategy: "visit-default";
380
+ readonly leadExports: readonly ["getLeadUi", "submitVisitLead", "submitContactLead", "slotsForDate", "expandVisitSchedule", "expandVisitTimeSlots", "isVisitSlotAllowed", "STUDIO_DEFAULT_VISIT_SCHEDULE"];
381
+ };
382
+ type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
383
+ declare function hasShowcaseLeadsPostUrl(text: string): boolean;
384
+ declare function coerceNpmVersion(raw: unknown): string | null;
385
+ declare function compareSemver(a: string, b: string): number;
386
+ declare function parseReactSdkNamedImports(source: string): string[];
387
+ declare function unavailableReactImports(source: string, pin: string): string[];
388
+ declare function studioSdkPinInstruction(): string;
389
+ declare function studioLeadInstruction(): string;
390
+ declare function studioChromeInstruction(): string;
391
+ /**
392
+ * Tokens that must not appear in Studio codegen (prompts, recipes, repair).
393
+ * v0 copies identifiers it sees, even inside “never import X”.
394
+ */
395
+ declare function studioCodegenContractViolations(text: string): string[];
396
+
235
397
  interface CreateGaragemClientOptions {
236
398
  /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
237
399
  baseUrl?: string;
@@ -316,6 +478,19 @@ interface GaragemClient {
316
478
  siteId?: string;
317
479
  next?: RequestNextOptions;
318
480
  }): Promise<CmsEntry>;
481
+ /** Visit/contact dialog schema (slots, labels). */
482
+ getLeadUi(args?: {
483
+ siteId?: string;
484
+ next?: RequestNextOptions;
485
+ }): Promise<LeadUi>;
486
+ /** POST a visit lead (`leadType: "visit"`). */
487
+ submitVisitLead(args: Omit<VisitLeadInput, "siteId" | "baseUrl" | "fetch"> & {
488
+ siteId?: string;
489
+ }): Promise<LeadSubmitResult>;
490
+ /** POST a contact lead (`leadType: "contact"`). */
491
+ submitContactLead(args: Omit<ContactLeadInput, "siteId" | "baseUrl" | "fetch"> & {
492
+ siteId?: string;
493
+ }): Promise<LeadSubmitResult>;
319
494
  }
320
495
  /**
321
496
  * Bind base URL, fetch and site to a single client object. Useful when
@@ -327,4 +502,4 @@ interface GaragemClient {
327
502
  */
328
503
  declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
329
504
 
330
- export { AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, ListingDetail, ListingFilters, ListingsResult, type LocationFilterInput, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, SEARCH_CSS_RECIPE, SEARCH_CSS_VARS, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, formatAreaM2, formatGroupedInteger, formatListingPrice, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getListing, getListings, getSearchUi, getSimilarListings, getSite, isStudioPreviewHost, listingBusinessLabel, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, parseAppliedSearchQuery, parseGroupedInteger, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery };
505
+ export { AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetLeadUiOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, type HHmm, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, ListingDetail, ListingFilters, ListingsResult, type LocationFilterInput, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, SEARCH_CSS_RECIPE, SEARCH_CSS_VARS, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, coerceNpmVersion, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, expandVisitSchedule, expandVisitTimeSlots, formatAreaM2, formatGroupedInteger, formatListingPrice, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getLeadUi, getListing, getListings, getSearchUi, getSimilarListings, getSite, hasShowcaseLeadsPostUrl, isStudioPreviewHost, isVisitSlotAllowed, listingBusinessLabel, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, parseAppliedSearchQuery, parseGroupedInteger, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery, slotsForDate, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLeadInstruction, studioSdkPinInstruction, submitContactLead, submitVisitLead, unavailableReactImports };
package/dist/index.d.ts CHANGED
@@ -147,6 +147,114 @@ declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntrie
147
147
  /** Fetch one published CMS entry by slug. */
148
148
  declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
149
149
 
150
+ /**
151
+ * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
152
+ * Calendar dates are civil dates in `timeZone` (America/Sao_Paulo), never
153
+ * UTC midnight from `new Date("YYYY-MM-DD")`.
154
+ */
155
+ declare const VISIT_TIME_ZONE: "America/Sao_Paulo";
156
+ type HHmm = string;
157
+ type VisitHours = {
158
+ start: HHmm;
159
+ end: HHmm;
160
+ };
161
+ type VisitScheduleConfig = {
162
+ timeZone: typeof VISIT_TIME_ZONE;
163
+ saturday: boolean;
164
+ sunday: boolean;
165
+ weekday: VisitHours;
166
+ weekend: VisitHours | null;
167
+ minHoursAhead: number;
168
+ };
169
+ type VisitSchedule = VisitScheduleConfig & {
170
+ disabledDays: number[];
171
+ weekdayTimeSlots: HHmm[];
172
+ weekendTimeSlots: HHmm[];
173
+ timeSlots: HHmm[];
174
+ };
175
+ declare function expandVisitTimeSlots(hours: VisitHours): HHmm[];
176
+ declare function expandVisitSchedule(config: VisitScheduleConfig): VisitSchedule;
177
+ declare const STUDIO_DEFAULT_VISIT_SCHEDULE: VisitSchedule;
178
+ declare function slotsForDate(schedule: VisitSchedule, date: Date | string, now?: Date): HHmm[];
179
+ declare function isVisitSlotAllowed(schedule: VisitSchedule, visitDate: string, visitTime: HHmm, now?: Date): boolean;
180
+
181
+ /**
182
+ * Headless visit / contact leads. Schema via GET /leads/ui; POST always
183
+ * goes to the webhook (`source: "site-sdk"`). v0 draws the dialog.
184
+ */
185
+
186
+ type LeadFieldId = "name" | "email" | "phone" | "message";
187
+ type LeadField = {
188
+ id: LeadFieldId;
189
+ required: boolean;
190
+ };
191
+ type LeadUi = {
192
+ defaultVariant: "visit";
193
+ timeZone: "America/Sao_Paulo";
194
+ variants: {
195
+ visit: {
196
+ ctaLabel: string;
197
+ requireDateTime: true;
198
+ schedule: VisitSchedule;
199
+ fields: LeadField[];
200
+ };
201
+ contact: {
202
+ ctaLabel: string;
203
+ requireDateTime: false;
204
+ whatsappPhone: string | null;
205
+ fields: LeadField[];
206
+ };
207
+ };
208
+ };
209
+ type GetLeadUiOptions = {
210
+ siteId: string;
211
+ baseUrl?: string;
212
+ fetch?: FetchLike;
213
+ next?: RequestNextOptions;
214
+ };
215
+ type LeadContact = {
216
+ name: string;
217
+ email?: string;
218
+ phone?: string;
219
+ message?: string;
220
+ };
221
+ type LeadSubmitBase = LeadContact & {
222
+ siteId: string;
223
+ baseUrl?: string;
224
+ fetch?: FetchLike;
225
+ listingId: string;
226
+ visitorId?: string;
227
+ brokerRef?: string;
228
+ referrer?: string;
229
+ };
230
+ type VisitLeadInput = LeadSubmitBase & {
231
+ visitDate: string;
232
+ visitTime: HHmm;
233
+ schedule?: VisitSchedule;
234
+ };
235
+ type ContactLeadInput = LeadSubmitBase;
236
+ type LeadSubmitResult = {
237
+ ok: true;
238
+ status: 202;
239
+ id: string;
240
+ };
241
+ type LeadSubmitErrorCode = "invalid_listing_id" | "invalid_contact" | "invalid_slot" | "rate_limited" | "not_found" | "http" | "network";
242
+ declare class LeadSubmitError extends Error {
243
+ readonly code: LeadSubmitErrorCode;
244
+ readonly status?: number;
245
+ readonly retryAfterSeconds?: number;
246
+ constructor(message: string, info: {
247
+ code: LeadSubmitErrorCode;
248
+ status?: number;
249
+ retryAfterSeconds?: number;
250
+ });
251
+ }
252
+ /** Fallback when GET /leads/ui fails — same default the API publishes. */
253
+ declare function studioDefaultLeadUi(): LeadUi;
254
+ declare function getLeadUi(options: GetLeadUiOptions): Promise<LeadUi>;
255
+ declare function submitVisitLead(input: VisitLeadInput): Promise<LeadSubmitResult>;
256
+ declare function submitContactLead(input: ContactLeadInput): Promise<LeadSubmitResult>;
257
+
150
258
  /** Public listing URLs. Prefer `listing.path` from the API; fallback is `/imoveis/id-{listingCode}`. */
151
259
  declare function listingLookupKey(raw: string): string;
152
260
  declare function listingPublicPath(listing: {
@@ -232,6 +340,60 @@ declare function isStudioPreviewHost(host: string): boolean;
232
340
  */
233
341
  declare function resolvePublicSiteId(options: ResolvePublicSiteIdOptions): Promise<string>;
234
342
 
343
+ /**
344
+ * Studio ↔ npm contract. Prompt, completeness, and recipes must read this
345
+ * object — do not keep a second list of required `@garagem-ai/site-sdk/react`
346
+ * names in apps/site.
347
+ *
348
+ * `minNpmVersion` is the tarball v0 actually installs. Optional exports exist
349
+ * in git and may already be on npm, but Studio codegen must not name them
350
+ * while chromeStrategy is self-inject (v0 copies identifiers; a layout tag
351
+ * also breaks the pancake stack).
352
+ */
353
+ declare const STUDIO_SDK_PACKAGE: "@garagem-ai/site-sdk";
354
+ declare const STUDIO_SDK_CONTRACT: {
355
+ readonly package: "@garagem-ai/site-sdk";
356
+ /**
357
+ * Exact pin for generated Studio sites. Must be ≥ `selfInjectSince` so
358
+ * prompts that skip the layout chrome tag match the tarball v0 installs.
359
+ * This PR’s changeset publishes that tarball as 0.4.3 — do not generate
360
+ * against this floor until Version Packages is on npm.
361
+ */
362
+ readonly minNpmVersion: "0.4.3";
363
+ /** First release where ListingCard and ResultsSkeleton inject the sheet. */
364
+ readonly selfInjectSince: "0.4.2";
365
+ readonly chromeStrategy: "self-inject";
366
+ readonly reactExports: readonly ["SearchPage", "ListingCard", "usePublicSearch", "ResultsSkeleton"];
367
+ /**
368
+ * Names that exist in git / the unpublished patch. Completeness treats an
369
+ * import as `sdk-export-mismatch` when the generated pin is older than
370
+ * `since`. Studio prompts must not mention these names at all (even as
371
+ * “never import”) — v0 copies the identifier and the preview ESM loader
372
+ * throws FatalRendererError.
373
+ */
374
+ readonly optionalReactExports: {
375
+ readonly SearchPageFallback: "0.4.1";
376
+ readonly SearchChromeStyles: "0.4.1";
377
+ };
378
+ readonly forbiddenImports: readonly ["@garagem-ai/site-sdk/react/search.css"];
379
+ readonly leadStrategy: "visit-default";
380
+ readonly leadExports: readonly ["getLeadUi", "submitVisitLead", "submitContactLead", "slotsForDate", "expandVisitSchedule", "expandVisitTimeSlots", "isVisitSlotAllowed", "STUDIO_DEFAULT_VISIT_SCHEDULE"];
381
+ };
382
+ type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
383
+ declare function hasShowcaseLeadsPostUrl(text: string): boolean;
384
+ declare function coerceNpmVersion(raw: unknown): string | null;
385
+ declare function compareSemver(a: string, b: string): number;
386
+ declare function parseReactSdkNamedImports(source: string): string[];
387
+ declare function unavailableReactImports(source: string, pin: string): string[];
388
+ declare function studioSdkPinInstruction(): string;
389
+ declare function studioLeadInstruction(): string;
390
+ declare function studioChromeInstruction(): string;
391
+ /**
392
+ * Tokens that must not appear in Studio codegen (prompts, recipes, repair).
393
+ * v0 copies identifiers it sees, even inside “never import X”.
394
+ */
395
+ declare function studioCodegenContractViolations(text: string): string[];
396
+
235
397
  interface CreateGaragemClientOptions {
236
398
  /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
237
399
  baseUrl?: string;
@@ -316,6 +478,19 @@ interface GaragemClient {
316
478
  siteId?: string;
317
479
  next?: RequestNextOptions;
318
480
  }): Promise<CmsEntry>;
481
+ /** Visit/contact dialog schema (slots, labels). */
482
+ getLeadUi(args?: {
483
+ siteId?: string;
484
+ next?: RequestNextOptions;
485
+ }): Promise<LeadUi>;
486
+ /** POST a visit lead (`leadType: "visit"`). */
487
+ submitVisitLead(args: Omit<VisitLeadInput, "siteId" | "baseUrl" | "fetch"> & {
488
+ siteId?: string;
489
+ }): Promise<LeadSubmitResult>;
490
+ /** POST a contact lead (`leadType: "contact"`). */
491
+ submitContactLead(args: Omit<ContactLeadInput, "siteId" | "baseUrl" | "fetch"> & {
492
+ siteId?: string;
493
+ }): Promise<LeadSubmitResult>;
319
494
  }
320
495
  /**
321
496
  * Bind base URL, fetch and site to a single client object. Useful when
@@ -327,4 +502,4 @@ interface GaragemClient {
327
502
  */
328
503
  declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
329
504
 
330
- export { AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, ListingDetail, ListingFilters, ListingsResult, type LocationFilterInput, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, SEARCH_CSS_RECIPE, SEARCH_CSS_VARS, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, formatAreaM2, formatGroupedInteger, formatListingPrice, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getListing, getListings, getSearchUi, getSimilarListings, getSite, isStudioPreviewHost, listingBusinessLabel, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, parseAppliedSearchQuery, parseGroupedInteger, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery };
505
+ export { AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetLeadUiOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, type HHmm, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, ListingDetail, ListingFilters, ListingsResult, type LocationFilterInput, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, SEARCH_CSS_RECIPE, SEARCH_CSS_VARS, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, coerceNpmVersion, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, expandVisitSchedule, expandVisitTimeSlots, formatAreaM2, formatGroupedInteger, formatListingPrice, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getLeadUi, getListing, getListings, getSearchUi, getSimilarListings, getSite, hasShowcaseLeadsPostUrl, isStudioPreviewHost, isVisitSlotAllowed, listingBusinessLabel, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, parseAppliedSearchQuery, parseGroupedInteger, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery, slotsForDate, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLeadInstruction, studioSdkPinInstruction, submitContactLead, submitVisitLead, unavailableReactImports };