@vepler/sdk 2.141.0 → 2.149.0

package/src/sdk/models/shared/planningapplication.ts

@@ -13,6 +13,10 @@ import {
   PlanningApplicant,
   PlanningApplicant$inboundSchema,
 } from "./planningapplicant.js";
+import {
+  PlanningClassificationReasoning,
+  PlanningClassificationReasoning$inboundSchema,
+} from "./planningclassificationreasoning.js";
 import {
   PlanningConstraint,
   PlanningConstraint$inboundSchema,
@@ -37,6 +41,7 @@ import {
   PlanningExtractionCoverage,
   PlanningExtractionCoverage$inboundSchema,
 } from "./planningextractioncoverage.js";
+import { PlanningImage, PlanningImage$inboundSchema } from "./planningimage.js";
 import {
   PlanningOfficerAssessmentExtractionEnvelope,
   PlanningOfficerAssessmentExtractionEnvelope$inboundSchema,
@@ -49,6 +54,10 @@ import {
   PlanningS106ExtractionEnvelope,
   PlanningS106ExtractionEnvelope$inboundSchema,
 } from "./plannings106extractionenvelope.js";
+import {
+  PlanningSemanticChunk,
+  PlanningSemanticChunk$inboundSchema,
+} from "./planningsemanticchunk.js";
 import {
   PlanningStatusHistory,
   PlanningStatusHistory$inboundSchema,
@@ -96,6 +105,20 @@ export type PlanningApplicationAddress = {
   ward?: string | null | undefined;
 };
 
+/**
+ * AI reasoning and processing artefacts behind the application: how it was classified (with confidence and uncertainty) and how its documents were segmented and summarised. Only present when 'enrichment' is requested via the include parameter. Sub-arrays may be empty when the relevant pipeline has not run for this application.
+ */
+export type Enrichment = {
+  /**
+   * AI classification reasoning runs for the application (most recent first). Shows how our pipeline determined the application's type, status and development category, with confidence and uncertainty. May be empty when no audit was recorded.
+   */
+  classification: Array<PlanningClassificationReasoning>;
+  /**
+   * Section-level structure and AI context summaries derived from the application's documents (no embeddings or full text). Conveys how the documents were segmented and understood. May be empty when semantic processing has not run.
+   */
+  semanticChunks: Array<PlanningSemanticChunk>;
+};
+
 /**
  * Structured, citation-backed data extracted from the application's documents — decision outcome and refusal reasons, development specifics, section 106 obligations, the officer's assessment, and consultee responses. Only present when 'extractions' is requested via the include parameter (GET) or the include array (POST /query); omitted entirely otherwise. Each sub-extraction may itself be null when that schema has not been extracted for this application. Coverage and per-extraction verification status are reported so consumers can degrade honestly when data is partial or unverified.
  */
@@ -352,6 +375,10 @@ export type PlanningApplication = {
    * Documents associated with the planning application, including submitted plans, decision notices, consultation responses, and supporting material. May be empty if no documents have been collected from the source.
    */
   documents?: Array<PlanningDocument> | undefined;
+  /**
+   * AI reasoning and processing artefacts behind the application: how it was classified (with confidence and uncertainty) and how its documents were segmented and summarised. Only present when 'enrichment' is requested via the include parameter. Sub-arrays may be empty when the relevant pipeline has not run for this application.
+   */
+  enrichment?: Enrichment | null | undefined;
   /**
    * The date on which the planning permission expires if not implemented, formatted as an ISO 8601 datetime string. Most permissions must be commenced within three years of approval. Null if not applicable or not recorded.
    */
@@ -364,6 +391,10 @@ export type PlanningApplication = {
    * Unique identifier for the planning application record. Use this UUID to retrieve the application via the GET /{applicationIds} endpoint.
    */
   id: string;
+  /**
+   * Deduplicated gallery of images (plans, elevations, photographs) extracted from the application's documents, each with a directly-renderable CDN URL. Only present when 'images' is requested via the include parameter. May be empty when no images have been extracted — image coverage is sparse, so expect this for most applications and render an honest empty state.
+   */
+  images?: Array<PlanningImage> | undefined;
   /**
    * The planning application reference number as assigned by the local planning authority. Format varies by council (e.g. 'APP/2024/0001', '24/00123/FUL', 'DC/24/0456'). This is the reference number a member of the public would use when contacting the council about the application.
    */
@@ -461,6 +492,26 @@ export function planningApplicationAddressFromJSON(
   );
 }
 
+/** @internal */
+export const Enrichment$inboundSchema: z.ZodType<
+  Enrichment,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  classification: z.array(PlanningClassificationReasoning$inboundSchema),
+  semanticChunks: z.array(PlanningSemanticChunk$inboundSchema),
+});
+
+export function enrichmentFromJSON(
+  jsonString: string,
+): SafeParseResult<Enrichment, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => Enrichment$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'Enrichment' from JSON`,
+  );
+}
+
 /** @internal */
 export const Extractions$inboundSchema: z.ZodType<
   Extractions,
@@ -697,9 +748,11 @@ export const PlanningApplication$inboundSchema: z.ZodType<
   developmentCategory: z.nullable(z.string()).optional(),
   distance: z.nullable(z.number()).optional(),
   documents: z.array(PlanningDocument$inboundSchema).optional(),
+  enrichment: z.nullable(z.lazy(() => Enrichment$inboundSchema)).optional(),
   expiryDate: z.nullable(z.string()).optional(),
   extractions: z.nullable(z.lazy(() => Extractions$inboundSchema)).optional(),
   id: z.string(),
+  images: z.array(PlanningImage$inboundSchema).optional(),
   key: z.string(),
   people: z.nullable(z.lazy(() => People$inboundSchema)).optional(),
   provider: z.string(),

package/src/sdk/models/shared/planningclassificationreasoning.ts

@@ -0,0 +1,69 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type PlanningClassificationReasoning = {
+  /**
+   * Version of the classification pipeline that produced this result.
+   */
+  classificationVersion?: string | null | undefined;
+  /**
+   * Per-dimension confidence detail behind the final classification.
+   */
+  confidenceBreakdown?: { [k: string]: any } | null | undefined;
+  /**
+   * ISO 8601 datetime when this classification run was recorded.
+   */
+  createdAt: string;
+  /**
+   * The ensemble's final classification result (type/status/category and supporting fields).
+   */
+  finalClassification?: { [k: string]: any } | null | undefined;
+  /**
+   * Natural-language explanation of how the classification was reached.
+   */
+  reasoning?: string | null | undefined;
+  /**
+   * Whether the pipeline flagged this classification for human review.
+   */
+  requiresHumanReview?: boolean | null | undefined;
+  /**
+   * Specific points of uncertainty the model surfaced (empty when none).
+   */
+  uncertaintyFlags?: Array<any> | undefined;
+  /**
+   * Issues flagged by the validation pass (empty when none).
+   */
+  validationIssues?: Array<any> | undefined;
+};
+
+/** @internal */
+export const PlanningClassificationReasoning$inboundSchema: z.ZodType<
+  PlanningClassificationReasoning,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  classificationVersion: z.nullable(z.string()).optional(),
+  confidenceBreakdown: z.nullable(z.record(z.any())).optional(),
+  createdAt: z.string(),
+  finalClassification: z.nullable(z.record(z.any())).optional(),
+  reasoning: z.nullable(z.string()).optional(),
+  requiresHumanReview: z.nullable(z.boolean()).optional(),
+  uncertaintyFlags: z.array(z.any()).optional(),
+  validationIssues: z.array(z.any()).optional(),
+});
+
+export function planningClassificationReasoningFromJSON(
+  jsonString: string,
+): SafeParseResult<PlanningClassificationReasoning, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PlanningClassificationReasoning$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PlanningClassificationReasoning' from JSON`,
+  );
+}

package/src/sdk/models/shared/planningdocument.ts

@@ -28,10 +28,18 @@ export type PlanningDocument = {
    * File size in bytes, if known. Null if the file size was not available from the source.
    */
   fileSize?: number | null | undefined;
+  /**
+   * Direct, publicly-readable URL to the document file (PDF) as stored and served by us via CDN — stable and CORS-enabled, suitable for rendering in-browser (unlike the council's sourceUrl, which may require cookies or expire). Present only when the 'content' expansion is requested via the include parameter. Null when we hold no stored copy of the file (fall back to sourceUrl).
+   */
+  fileUrl?: string | null | undefined;
   /**
    * Unique identifier for the document record.
    */
   id: string;
+  /**
+   * Direct, publicly-readable CDN URL to the extracted text of the document, as Markdown. Produced by our OCR/conversion pipeline. Present only when the 'content' expansion is requested. Null when the document has not been OCR-processed (no text is available).
+   */
+  ocrUrl?: string | null | undefined;
   /**
    * Number of pages in the document, if known. Primarily available for PDF documents.
    */
@@ -57,7 +65,9 @@ export const PlanningDocument$inboundSchema: z.ZodType<
   documentTypeDetailed: z.nullable(z.string()).optional(),
   fileName: z.string(),
   fileSize: z.nullable(z.number()).optional(),
+  fileUrl: z.nullable(z.string()).optional(),
   id: z.string(),
+  ocrUrl: z.nullable(z.string()).optional(),
   pageCount: z.nullable(z.number()).optional(),
   planningApplicationId: z.string(),
   sourceUrl: z.string(),

package/src/sdk/models/shared/planningimage.ts

@@ -0,0 +1,79 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type PlanningImage = {
+  /**
+   * AI classification of what the image depicts (e.g. 'site_plan', 'elevation', 'floor_plan', 'location_plan', 'photograph'). Null when the image has not yet been classified.
+   */
+  classification?: string | null | undefined;
+  /**
+   * Confidence in the classification, 0–1. Null when unclassified.
+   */
+  classificationConfidence?: number | null | undefined;
+  /**
+   * File name of the source document the image was extracted from, when known.
+   */
+  documentFileName?: string | null | undefined;
+  /**
+   * Image height in pixels, if known.
+   */
+  height?: number | null | undefined;
+  /**
+   * Unique identifier for the canonical image (deduplicated within the application).
+   */
+  id: string;
+  /**
+   * Image MIME type.
+   */
+  mimeType?: string | null | undefined;
+  /**
+   * Page of the source document on which this image first appears (1-based).
+   */
+  pageNumber?: number | null | undefined;
+  /**
+   * How many times this image appears across the application's documents. A higher count often indicates a recurring key drawing (e.g. a site plan repeated in several documents).
+   */
+  refCount?: number | undefined;
+  /**
+   * Publicly-readable CDN URL for the image, suitable for direct rendering in an <img> tag. Stable and CORS-enabled.
+   */
+  url: string;
+  /**
+   * Image width in pixels, if known.
+   */
+  width?: number | null | undefined;
+};
+
+/** @internal */
+export const PlanningImage$inboundSchema: z.ZodType<
+  PlanningImage,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  classification: z.nullable(z.string()).optional(),
+  classificationConfidence: z.nullable(z.number()).optional(),
+  documentFileName: z.nullable(z.string()).optional(),
+  height: z.nullable(z.number()).optional(),
+  id: z.string(),
+  mimeType: z.nullable(z.string()).optional(),
+  pageNumber: z.nullable(z.number()).optional(),
+  refCount: z.number().optional(),
+  url: z.string(),
+  width: z.nullable(z.number()).optional(),
+});
+
+export function planningImageFromJSON(
+  jsonString: string,
+): SafeParseResult<PlanningImage, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PlanningImage$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PlanningImage' from JSON`,
+  );
+}

package/src/sdk/models/shared/planningqueryrequest.ts

@@ -12,6 +12,9 @@ import {
 
 export const Include = {
   Extractions: "extractions",
+  Images: "images",
+  Content: "content",
+  Enrichment: "enrichment",
 } as const;
 export type Include = ClosedEnum<typeof Include>;
 
@@ -48,7 +51,7 @@ export type PlanningQueryRequestSortOrder = ClosedEnum<
 
 export type PlanningQueryRequest = {
   /**
-   * Optional expansions to attach to each returned application. 'extractions' attaches structured, citation-backed extractions (decision, development, s106, officer assessment, consultee responses). Omitted by default to keep responses lean — extractions are large. Request only when you need the detail (e.g. a handful of specific applications), not for bulk aggregation.
+   * Optional expansions to attach to each returned application. 'extractions' — structured, citation-backed extractions (decision, development, s106, officer assessment, consultee responses). 'images' — a deduplicated image gallery with directly-renderable CDN URLs. 'content' — adds fileUrl (CDN PDF) and ocrUrl (CDN Markdown text) to each document so it can be rendered/searched in-browser. 'enrichment' — AI classification reasoning and document segmentation summaries. All are omitted by default to keep responses lean; request only what you need (e.g. a handful of specific applications), not for bulk aggregation.
    */
   include?: Array<Include> | undefined;
   /**

package/src/sdk/models/shared/planningsemanticchunk.ts

@@ -0,0 +1,64 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type PlanningSemanticChunk = {
+  /**
+   * Kind of chunk (e.g. 'document', 'section').
+   */
+  chunkType?: string | null | undefined;
+  /**
+   * AI-written summary giving the surrounding context of this chunk.
+   */
+  contextSummary?: string | null | undefined;
+  /**
+   * UUID of the source document this chunk belongs to.
+   */
+  documentId?: string | null | undefined;
+  /**
+   * Unique identifier for the semantic chunk.
+   */
+  id: string;
+  /**
+   * Last page the chunk spans (1-based).
+   */
+  pageEnd?: number | null | undefined;
+  /**
+   * First page the chunk spans (1-based).
+   */
+  pageStart?: number | null | undefined;
+  /**
+   * Hierarchical section heading path locating the chunk within the document.
+   */
+  sectionPath?: Array<string> | null | undefined;
+};
+
+/** @internal */
+export const PlanningSemanticChunk$inboundSchema: z.ZodType<
+  PlanningSemanticChunk,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  chunkType: z.nullable(z.string()).optional(),
+  contextSummary: z.nullable(z.string()).optional(),
+  documentId: z.nullable(z.string()).optional(),
+  id: z.string(),
+  pageEnd: z.nullable(z.number()).optional(),
+  pageStart: z.nullable(z.number()).optional(),
+  sectionPath: z.nullable(z.array(z.string())).optional(),
+});
+
+export function planningSemanticChunkFromJSON(
+  jsonString: string,
+): SafeParseResult<PlanningSemanticChunk, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PlanningSemanticChunk$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PlanningSemanticChunk' from JSON`,
+  );
+}

package/src/sdk/models/shared/searchresult.ts

@@ -70,7 +70,7 @@ export type SearchResult = {
    */
   location?: SearchResultCoordinates | undefined;
   /**
-   * Primary display text — building + street
+   * Primary display text: building + street
    */
   mainText?: string | undefined;
   /**
@@ -102,7 +102,7 @@ export type SearchResult = {
    */
   score: number;
   /**
-   * Secondary display text — locality + postcode
+   * Secondary display text: locality + postcode
    */
   secondaryText?: string | undefined;
   /**

package/src/sdk/planning.ts

@@ -15,7 +15,7 @@ export class Planning extends ClientSDK {
    * Get planning applications by application IDs
    *
    * @remarks
-   * Retrieve one or more planning applications by their internal UUIDs. Provide up to 100 comma-separated application IDs in the path. Returns the matching applications in a paginated list response. If you have council reference numbers rather than UUIDs, use the GET /sources/{sourceIds} endpoint instead. Pass ?include=extractions to attach structured, citation-backed extractions to each application.
+   * Retrieve one or more planning applications by their internal UUIDs. Provide up to 100 comma-separated application IDs in the path. Returns the matching applications in a paginated list response. If you have council reference numbers rather than UUIDs, use the GET /sources/{sourceIds} endpoint instead. Use ?include= to attach optional expansions (comma-separated): 'extractions' (structured, citation-backed extractions), 'images' (a renderable image gallery), 'content' (fileUrl + ocrUrl on each document), 'enrichment' (AI classification reasoning and document summaries).
    */
   async getPlanningApplications(
     request: operations.GetPlanningApplicationsRequest,
@@ -32,7 +32,7 @@ export class Planning extends ClientSDK {
    * Get planning applications by source IDs
    *
    * @remarks
-   * Retrieve one or more planning applications by their source identifiers. Each source ID uses the format 'provider::key' where provider is the council slug and key is the council's reference number (e.g. 'lambeth::24/00123/FUL'). Provide up to 100 comma-separated source IDs in the path. This is the recommended lookup method when you know the council and application reference number. Pass ?include=extractions to attach structured, citation-backed extractions to each application.
+   * Retrieve one or more planning applications by their source identifiers. Each source ID uses the format 'provider::key' where provider is the council slug and key is the council's reference number (e.g. 'lambeth::24/00123/FUL'). Provide up to 100 comma-separated source IDs in the path. This is the recommended lookup method when you know the council and application reference number. Use ?include= to attach optional expansions (comma-separated): 'extractions' (structured, citation-backed extractions), 'images' (a renderable image gallery), 'content' (fileUrl + ocrUrl on each document), 'enrichment' (AI classification reasoning and document summaries).
    */
   async getPlanningApplicationsBySource(
     request: operations.GetPlanningApplicationsBySourceRequest,
@@ -49,7 +49,7 @@ export class Planning extends ClientSDK {
    * Query planning applications with advanced filters
    *
    * @remarks
-   * Search for planning applications using a combination of filters including council, status, type, development category, and date ranges. Use the `near` filter ({ lat, lng, radiusM }) to retrieve applications around a point — the primary way to find a property's planning context; results come back closest-first with `distance` (metres) populated. Pass `include: ["extractions"]` to attach structured, citation-backed extractions. Filters within the query object are combined with AND logic, whilst array values within a single filter use OR logic. Results are paginated and can be sorted by any date field (the `near` filter overrides sort with closest-first). Supports up to 100 results per page.
+   * Search for planning applications using a combination of filters including council, status, type, development category, and date ranges. Use the `near` filter ({ lat, lng, radiusM }) to retrieve applications around a point — the primary way to find a property's planning context; results come back closest-first with `distance` (metres) populated. Pass `include` (any of `["extractions", "images", "content", "enrichment"]`) to attach structured citation-backed extractions, a renderable image gallery, document fileUrl/ocrUrl, and/or AI classification reasoning. Filters within the query object are combined with AND logic, whilst array values within a single filter use OR logic. Results are paginated and can be sorted by any date field (the `near` filter overrides sort with closest-first). Supports up to 100 results per page.
    */
   async searchPlanningApplications(
     request?: shared.PlanningQueryRequest | undefined,

package/src/sdk/search.ts

@@ -14,6 +14,12 @@ export class Search extends ClientSDK {
    *
    * @remarks
    * Simple autocomplete for UK properties and locations. Searches across Address and Location sources with fuzzy matching. Automatically detects query type (postcode, address, place name) and returns suggestions.
+   *
+   * Optionally accepts a geographic centre point (`lat`, `lng`) to make results proximity-aware:
+   * - `geo_mode=bias` (default): soft preference. The best textual matches near the point rank higher, but distant matches are still returned.
+   * - `geo_mode=restrict`: hard cutoff. Only address results within `radius_meters` of the point are returned.
+   *
+   * When a centre point is supplied, address results include a `distance` (metres from the point). Geographic ranking applies to the address source, so pair it with `source=address` for the most predictable proximity results.
    */
   async searchSuggest(
     request: operations.SearchSuggestRequest,