@gscdump/sdk 0.37.7 → 0.38.0

package/README.md

@@ -2,6 +2,13 @@
 
 Consumer SDK for hosted gscdump.com integrations.
 
+> The descriptor-driven HTTP client and ticketed realtime state machine are
+> exported from `@gscdump/sdk/v1`. Existing root HTTP/realtime clients remain
+> legacy compatibility surfaces during the release and cutover overlap; the
+> legacy socket client still sends a long-lived key in its first frame and must
+> not be used for a v1 browser integration. See the
+> [v1 contract](../../docs/hosted-api-v1.md).
+
 This package is for partner applications that consume gscdump.com APIs,
 webhooks, and realtime events. Callers inject the HTTP transport and auth they
 want to use; route construction stays inside the hosted adapter.
@@ -18,6 +25,22 @@ const gscdump = createGscdumpClient({
 const { sites } = await gscdump.getUserSites(userId)
 ```
 
+The initial v1 slice uses a server-held Bearer credential and exposes both a
+generic operation executor and four convenience methods:
+
+```ts
+import { createGscdumpV1Client } from '@gscdump/sdk/v1'
+
+const gscdump = createGscdumpV1Client({
+  credential: () => process.env.GSCDUMP_API_KEY!,
+  fetch,
+})
+
+const lifecycle = await gscdump.getUserLifecycle({
+  params: { userId: 'u_01' },
+})
+```
+
 ## Scope
 
 - Partner user lifecycle
@@ -28,10 +51,17 @@ const { sites } = await gscdump.getUserSites(userId)
 - Webhook receiver contracts and HMAC verification helpers
 - Shared request/response types re-exported from `@gscdump/contracts`
 
-Analyzer Source dispatch, browser DuckDB-WASM boot, R2 parquet attach, and
-Nuxt composables remain in `@gscdump/nuxt`. Nuxt apps should install
-`@gscdump/nuxt` for dashboard reads; that layer uses
-`createAnalyticsClient()` internally.
+Analyzer Source dispatch, browser DuckDB-WASM boot, and R2 parquet attach are
+separate engine/Nuxt concerns. A Nuxt app can consume the hosted SDK through
+its own query layer; the current consumer uses `nuxt-use-query` rather than
+making the public API depend on `@gscdump/nuxt`.
+
+For v1, a Nuxt consumer keeps `user_key` and `partner_key` credentials on its
+server and exposes proxy paths that retain the upstream surface and major
+(for example `/api/gscdump/analytics/v1/...`). Browser realtime receives only
+a single-use ticket. Every semantic event's `changes[]` maps to one ordered,
+awaited query-cache effect; unsafe resync purges the whole host-owned cache
+scope and primary-reseeds it before the SDK advances its cursor or ACKs.
 
 ## Boundary
 
@@ -42,7 +72,8 @@ Belongs here:
 
 - request/response types and schemas for partner apps
 - route builders and pluggable HTTP clients
-- websocket client and event schemas
+- ticketed websocket client, replay/resync state, and event schemas
+- awaited realtime apply/resync hooks; a rejected effect never advances ACK
 - webhook header constants, event schemas, parsing, normalization, and signature
   verification for receivers
 
@@ -54,6 +85,7 @@ Does not belong here:
 - generating or storing production webhook secrets
 - creating production webhook delivery IDs or envelopes
 - partner subscription filtering for outgoing deliveries
+- Durable Object stream storage, replay retention, or outbox dispatch
 
 ## Webhooks
 

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { query_d_exports } from "./_chunks/query.mjs";
 import { Result } from "gscdump/result";
 import { AddPartnerTeamMemberParams, AnalyticsClient, AnalyticsClient as AnalyticsClient$1, BackfillRange, BackfillResponse, BindPartnerSiteTeamParams, BuilderState, BulkRegisterPartnerSiteResult, BulkRegisterPartnerSitesParams, BulkRegisterPartnerSitesResponse, CANONICAL_WEBHOOK_EVENTS, CanonicalWebhookEventType, CreatePartnerTeamParams, CreateWebhookEnvelopeOptions, DataDetailOptions, DataQueryOptions, DeletePartnerUserResponse, GscComparisonFilter, GscdumpAnalysisParams, GscdumpAnalysisPreset, GscdumpAnalysisResponse, GscdumpAnalysisSourcesResponse, GscdumpAvailableSite, GscdumpCanonicalMismatchesResponse, GscdumpDataDetailResponse, GscdumpDataResponse, GscdumpDataRow, GscdumpDateRangeParams, GscdumpIndexPercentResponse, GscdumpIndexingDiagnosticsResponse, GscdumpIndexingResponse, GscdumpIndexingUrlStatus, GscdumpIndexingUrlsResponse, GscdumpKeywordSparklinesParams, GscdumpKeywordSparklinesResponse, GscdumpMeta, GscdumpPageTrendParams, GscdumpPageTrendResponse, GscdumpPermissionRecovery, GscdumpQueryTrendParams, GscdumpQueryTrendResponse, GscdumpSiteRegistration, GscdumpSitemap, GscdumpSitemapChangesResponse, GscdumpSitemapHistory, GscdumpSitemapsResponse, GscdumpSyncStatusResponse, GscdumpSyncStatusResponse as GscdumpSyncStatusResponse$1, GscdumpTeamMemberRow, GscdumpTeamRow, GscdumpTopAssociationParams, GscdumpTopAssociationResponse, GscdumpTotals, GscdumpUserRegistration, GscdumpUserSettings, GscdumpUserSite, GscdumpUserSite as GscdumpUserSite$1, GscdumpUserStatus, GscdumpUserTokenUpdate, IndexingDiagnosticsParams, IndexingUrlsParams, InspectionHistoryResponse, InspectionIndex, PartnerClient, PartnerClient as PartnerClient$1, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleResponse as PartnerLifecycleResponse$1, PartnerLifecycleSite, PartnerLifecycleSite as PartnerLifecycleSite$1, PartnerRealtimeEvent, PartnerRealtimeEvent as PartnerRealtimeEvent$1, PartnerRealtimeEventType, PartnerRealtimeMessage, PartnerRealtimeMessage as PartnerRealtimeMessage$1, PartnerWebhookData, PartnerWebhookHeaders, PartnerWebhookHeaders as PartnerWebhookHeaders$1, RealtimeAuthFailedEvent, RealtimeAuthRequiredMessage, RealtimeConnectedMessage, RealtimeEnrichmentCompleteEvent, RealtimeErrorMessage, RealtimeJobFailedEvent, RealtimeNeedsReauthEvent, RealtimePongMessage, RealtimeSiteAddedEvent, RealtimeSiteRemovedEvent, RealtimeSubscribedMessage, RealtimeSyncCompleteEvent, RealtimeSyncFailedEvent, RealtimeSyncJobCompleteEvent, RealtimeSyncProgressEvent, RealtimeSyncSiteCompleteEvent, RegisterPartnerSiteParams, RegisterPartnerUserParams, RollupEnvelope, UpdatePartnerUserTokensParams, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WebhookEnvelope, WebhookEnvelope as WebhookEnvelope$1, WebhookEventType, WhoamiResponse } from "@gscdump/contracts";
+import { ZodTypeAny } from "zod";
 import { ActionSource } from "@gscdump/analysis";
 import { AnalysisTool } from "@gscdump/engine/analysis-types";
 export * from "@gscdump/contracts";
@@ -127,7 +128,7 @@ interface GscAnalyzerDefinition<TComponent = unknown> {
   capabilities?: GscAnalyzerCapabilities<TComponent>;
 }
 type GscAnalyzerDefinitionWithCapability<K extends GscAnalyzerCapability, TComponent = unknown> = GscAnalyzerDefinition<TComponent> & {
-  capabilities: { [P in K]: NonNullable<GscAnalyzerCapabilities<TComponent>[P]> };
+  capabilities: { [P in K]: NonNullable<GscAnalyzerCapabilities<TComponent>[P]>; };
 };
 declare function defineGscAnalyzer<TComponent = unknown>(def: GscAnalyzerDefinition<TComponent>): GscAnalyzerDefinition<TComponent>;
 interface DailyAnonInput {

package/dist/query.d.mts

@@ -1 +1,2 @@
+import "./_chunks/query.mjs";
 export * from "gscdump/query";

package/dist/v1/index.d.mts

@@ -0,0 +1,187 @@
+import { GscdumpV1ErrorEnvelope, RealtimeV1Cursor, RealtimeV1Event, RealtimeV1StreamHead, RealtimeV1StreamId, createGscdumpV1Protocol } from "@gscdump/contracts/v1";
+import { ZodTypeAny, z } from "zod";
+type MaybePromise$1<T> = T | Promise<T>;
+type ValueOf<T> = T[keyof T];
+type ValueOfUnion<T> = T extends unknown ? ValueOf<T> : never;
+type GscdumpV1ProtocolShape = ReturnType<typeof createGscdumpV1Protocol>;
+type GscdumpV1Surface = ValueOf<GscdumpV1ProtocolShape['surfaces']>;
+type GscdumpV1OperationRegistry = GscdumpV1Surface['operations'];
+type GscdumpV1Operation = ValueOfUnion<GscdumpV1OperationRegistry>;
+type GscdumpV1OperationId = GscdumpV1Operation['id'];
+type OperationById<TId extends GscdumpV1OperationId> = Extract<GscdumpV1Operation, {
+  id: TId;
+}>;
+type SchemaInput<TSchema> = TSchema extends ZodTypeAny ? z.input<TSchema> : never;
+type SchemaOutput<TSchema> = TSchema extends ZodTypeAny ? z.output<TSchema> : never;
+type RequiredLocation<TKey extends string, TSchema> = TSchema extends ZodTypeAny ? { [K in TKey]: SchemaInput<TSchema>; } : { [K in TKey]?: never; };
+type OptionalLocation<TKey extends string, TSchema> = TSchema extends ZodTypeAny ? { [K in TKey]?: SchemaInput<TSchema>; } : { [K in TKey]?: never; };
+type GscdumpV1OperationInput<TId extends GscdumpV1OperationId> = RequiredLocation<'params', OperationById<TId>['request']['params']> & RequiredLocation<'query', OperationById<TId>['request']['query']> & OptionalLocation<'headers', OperationById<TId>['request']['headers']> & RequiredLocation<'body', OperationById<TId>['request']['body']>;
+type OperationResponseSchema<TId extends GscdumpV1OperationId> = ValueOf<OperationById<TId>['responses']> extends (infer TResponse) ? TResponse extends {
+  client: infer TClient extends ZodTypeAny;
+} ? TClient : never : never;
+type GscdumpV1OperationResponse<TId extends GscdumpV1OperationId> = SchemaOutput<OperationResponseSchema<TId>>;
+type GscdumpV1CredentialResolver = string | (() => MaybePromise$1<string>);
+type GscdumpV1HeadersResolver = HeadersInit | (() => MaybePromise$1<HeadersInit>);
+interface GscdumpV1RetryOptions {
+  /** Total attempts, including the initial request. Defaults to 3 and is capped at 5. */
+  maxAttempts?: number;
+  /** Deterministic exponential-backoff base. Defaults to 250 ms. */
+  baseDelayMs?: number;
+  /** Backoff ceiling. Defaults to 2 seconds. Retry-After can exceed this ceiling. */
+  maxDelayMs?: number;
+}
+interface CreateGscdumpV1ClientOptions {
+  /**
+   * Root replacing the contract's `/api` segment. Direct calls default to
+   * `https://gscdump.com/api`; a same-origin proxy can use `/api/_gscdump`.
+   */
+  apiRoot?: string;
+  credential: GscdumpV1CredentialResolver;
+  fetch?: typeof fetch;
+  headers?: GscdumpV1HeadersResolver;
+  retry?: GscdumpV1RetryOptions;
+}
+interface GscdumpV1ExecuteOptions {
+  signal?: AbortSignal;
+  requestId?: string;
+  idempotencyKey?: string;
+}
+type GscdumpV1SdkErrorCode = GscdumpV1ErrorEnvelope['error']['code'] | 'aborted' | 'credential_resolution' | 'network_error' | 'protocol_error' | 'request_validation' | 'response_validation';
+interface GscdumpV1ErrorOptions {
+  code: GscdumpV1SdkErrorCode;
+  message: string;
+  status?: number;
+  requestId?: string;
+  retryable: boolean;
+  details: Record<string, unknown>;
+  cause?: unknown;
+}
+/** One stable, tagged failure shape for validation, transport, and API errors. */
+declare class GscdumpV1Error extends Error {
+  readonly tag: "GscdumpV1Error";
+  readonly code: GscdumpV1SdkErrorCode;
+  readonly status?: number;
+  readonly requestId?: string;
+  readonly retryable: boolean;
+  readonly details: Record<string, unknown>;
+  readonly cause?: unknown;
+  constructor(options: GscdumpV1ErrorOptions);
+}
+declare function isGscdumpV1Error(error: unknown): error is GscdumpV1Error;
+interface GscdumpV1Client {
+  execute: <TId extends GscdumpV1OperationId>(operation: TId, input: GscdumpV1OperationInput<TId>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<TId>>;
+  getUserLifecycle: (input: GscdumpV1OperationInput<'partner.users.lifecycle.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.lifecycle.get'>>;
+  queryAnalyticsRows: (input: GscdumpV1OperationInput<'analytics.rows.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'analytics.rows.query'>>;
+  getRealtimeStreamHead: (input?: GscdumpV1OperationInput<'realtime.stream.head.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'realtime.stream.head.get'>>;
+  createRealtimeTicket: (input: GscdumpV1OperationInput<'realtime.tickets.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'realtime.tickets.create'>>;
+}
+/** Create one framework-neutral client whose behavior is driven by the v1 registry. */
+declare function createGscdumpV1Client(options: CreateGscdumpV1ClientOptions): GscdumpV1Client;
+type MaybePromise<T> = T | Promise<T>;
+declare const GSCDUMP_REALTIME_V1_SDK_VERSION: "0.37.7";
+type GscdumpRealtimeV1TransportState = 'idle' | 'ticketing' | 'connecting' | 'handshaking' | 'replaying' | 'live' | 'waiting' | 'stopped' | 'terminal';
+type GscdumpRealtimeV1Freshness = 'unknown' | 'stale' | 'applying' | 'fresh' | 'resyncing' | 'degraded';
+type GscdumpRealtimeV1ErrorCode = 'cursor_store_failed' | 'effect_failed' | 'heartbeat_stale' | 'integration_failed' | 'protocol_error' | 'resync_failed' | 'runtime_unavailable' | 'socket_error' | 'ticket_invalid' | 'ticket_provider_failed' | 'upgrade_rejected';
+interface GscdumpRealtimeV1ErrorOptions {
+  code: GscdumpRealtimeV1ErrorCode;
+  message: string;
+  retryable: boolean;
+  terminal: boolean;
+  details?: Record<string, unknown>;
+  cause?: unknown;
+}
+declare class GscdumpRealtimeV1Error extends Error {
+  readonly tag: "GscdumpRealtimeV1Error";
+  readonly code: GscdumpRealtimeV1ErrorCode;
+  readonly retryable: boolean;
+  readonly terminal: boolean;
+  readonly details: Record<string, unknown>;
+  readonly cause?: unknown;
+  constructor(options: GscdumpRealtimeV1ErrorOptions);
+}
+interface GscdumpRealtimeV1CursorStore {
+  load: () => MaybePromise<RealtimeV1Cursor | null>;
+  save: (cursor: RealtimeV1Cursor) => MaybePromise<void>;
+}
+interface GscdumpRealtimeV1SocketLike {
+  readonly readyState: number;
+  readonly protocol: string;
+  onopen: ((event: unknown) => void) | null;
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onclose: ((event: {
+    code?: number;
+    reason?: string;
+    wasClean?: boolean;
+  }) => void) | null;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+}
+interface GscdumpRealtimeV1Runtime {
+  createSocket: (url: string, protocols: readonly string[]) => GscdumpRealtimeV1SocketLike;
+  setTimeout: (handler: () => void, ms: number) => unknown;
+  clearTimeout: (handle: unknown) => void;
+  random: () => number;
+  now: () => number;
+}
+type GscdumpRealtimeV1ResyncReason = 'cursor_expired' | 'retention_gap' | 'sequence_gap' | 'stream_mismatch' | 'initial_cursor_missing' | 'effect_application_failed';
+interface GscdumpRealtimeV1ResyncRequest {
+  reason: GscdumpRealtimeV1ResyncReason;
+  source: 'server' | 'client';
+  streamId: RealtimeV1StreamId;
+  previousCursor: RealtimeV1Cursor | null;
+  resumeAfter: RealtimeV1Cursor;
+  failedEvent?: RealtimeV1Event;
+  cause?: unknown;
+}
+interface GscdumpRealtimeV1Snapshot {
+  transport: GscdumpRealtimeV1TransportState;
+  freshness: GscdumpRealtimeV1Freshness;
+  attempt: number;
+  streamId: RealtimeV1StreamId | null;
+  cursor: RealtimeV1Cursor | null;
+  head: RealtimeV1StreamHead | null;
+  error: GscdumpRealtimeV1Error | null;
+}
+type GscdumpRealtimeV1Observation = {
+  type: 'state';
+  state: GscdumpRealtimeV1Snapshot;
+} | {
+  type: 'event';
+  event: RealtimeV1Event;
+  cursor: RealtimeV1Cursor | null;
+} | {
+  type: 'error';
+  error: GscdumpRealtimeV1Error;
+  state: GscdumpRealtimeV1Snapshot;
+} | {
+  type: 'advisory';
+  code: 'unknown_event' | 'unknown_resource' | 'unsupported_event_version';
+  event: RealtimeV1Event;
+};
+interface CreateGscdumpRealtimeV1ClientOptions {
+  /** Called for every connection attempt. A ticket is never reused. */
+  ticketProvider: () => MaybePromise<unknown>;
+  /** Required correctness effect for each contiguous durable event. */
+  applyEvent: (event: RealtimeV1Event) => Promise<void>;
+  /** Required full authoritative reseed used whenever replay is unsafe. */
+  resync: (request: GscdumpRealtimeV1ResyncRequest) => Promise<void>;
+  cursorStore?: GscdumpRealtimeV1CursorStore;
+  /** One isolated callback for state, event, advisory, and error observations. */
+  onObservation?: (observation: GscdumpRealtimeV1Observation) => unknown;
+  runtime?: GscdumpRealtimeV1Runtime;
+  sdkVersion?: string;
+}
+interface GscdumpRealtimeV1Client {
+  start: () => Promise<void>;
+  stop: () => void;
+  getSnapshot: () => GscdumpRealtimeV1Snapshot;
+}
+/**
+ * Own the v1 cursor/ACK correctness state machine. Framework adapters provide
+ * required effects; they never need to reproduce transport ordering rules.
+ */
+declare function createGscdumpRealtimeV1Client(options: CreateGscdumpRealtimeV1ClientOptions): GscdumpRealtimeV1Client;
+export { type CreateGscdumpRealtimeV1ClientOptions, type CreateGscdumpV1ClientOptions, GSCDUMP_REALTIME_V1_SDK_VERSION, type GscdumpRealtimeV1Client, type GscdumpRealtimeV1CursorStore, GscdumpRealtimeV1Error, type GscdumpRealtimeV1ErrorCode, type GscdumpRealtimeV1ErrorOptions, type GscdumpRealtimeV1Freshness, type GscdumpRealtimeV1Observation, type GscdumpRealtimeV1ResyncReason, type GscdumpRealtimeV1ResyncRequest, type GscdumpRealtimeV1Runtime, type GscdumpRealtimeV1Snapshot, type GscdumpRealtimeV1SocketLike, type GscdumpRealtimeV1TransportState, type GscdumpV1Client, type GscdumpV1CredentialResolver, GscdumpV1Error, type GscdumpV1ErrorOptions, type GscdumpV1ExecuteOptions, type GscdumpV1HeadersResolver, type GscdumpV1Operation, type GscdumpV1OperationId, type GscdumpV1OperationInput, type GscdumpV1OperationResponse, type GscdumpV1RetryOptions, type GscdumpV1SdkErrorCode, createGscdumpRealtimeV1Client, createGscdumpV1Client, isGscdumpV1Error };