@tmturtle/http-client 1.0.0

package/README.md

@@ -0,0 +1,36 @@
+# Trademark Turtle HTTP Client
+
+Typed access to Trademark Turtle search, exact trademark identities, listing
+text matching, reports, account context, and service status.
+
+## Install
+
+```sh
+bun add @tmturtle/http-client
+```
+
+## Use
+
+```ts
+import { createTmturtleClient } from "@tmturtle/http-client";
+
+const client = createTmturtleClient({
+  apiKey: process.env.TMTURTLE_API_KEY!,
+  baseUrl: "https://tmturtle.merchbase.co",
+});
+
+const results = await client.trademarks.search.query({
+  match: "both",
+  mode: "multi",
+  query: "turtle club",
+  status: "live",
+});
+
+const trademark = await client.trademarks.get.query({
+  serialNumber: "60146682",
+});
+```
+
+The package exports `TmturtleClient`, `TmturtleRouterInputs`, and
+`TmturtleRouterOutputs`. See the [HTTP API reference](https://github.com/merchbaseco/tmturtle/blob/main/docs/reference/http-api.md)
+for authorization, procedure, pagination, and error contracts.

package/dist/index.d.mts

@@ -0,0 +1,532 @@
+import { CreateTRPCClient } from "@trpc/client";
+import { inferRouterInputs, inferRouterOutputs } from "@trpc/server";
+//#region ../../apps/server/src/ingestion/mark-types.d.ts
+declare const markVersions: {
+  readonly authorityPolicy: "uspto-authority-v1";
+  readonly normalization: "uspto-normalization-v1";
+  readonly projection: "uspto-projection-v2";
+  readonly sourceProfile: "uspto-application-xml-v2.0-v1";
+};
+type MarkVersions = Omit<typeof markVersions, "projection"> & {
+  projection: string;
+};
+interface SourceContributor {
+  artifactVersionSha256: string;
+  claimPath: string;
+  group: "mark-presentation";
+  physicalRecordIndex: number;
+  product: string;
+}
+type MarkType = "design" | "other" | "text" | "typeset";
+interface MarkClass {
+  internationalCode: string | null;
+  statusCode: string | null;
+  statusDate: string | null;
+}
+interface MarkGoodsServices {
+  text: string | null;
+  typeCode: string | null;
+}
+interface MarkOwner {
+  entryNumber: string | null;
+  partyName: string | null;
+  partyType: string | null;
+}
+interface MarkStatusEvent {
+  code: string | null;
+  date: string | null;
+  description: string | null;
+  number: string | null;
+  type: string | null;
+}
+interface ProjectedMark {
+  classes: MarkClass[];
+  contributors: SourceContributor[];
+  goodsServices: MarkGoodsServices[];
+  kind: "resolved";
+  mark: {
+    filingDate: string | null;
+    markDrawingCode: string | null;
+    registrationDate: string | null;
+    registrationNumber: string | null;
+    serialNumber: string;
+    sourceTransactionDate: string | null;
+    statusCode: string | null;
+    statusDate: string | null;
+    wordMark: string | null;
+  };
+  owners: MarkOwner[];
+  statusEvents: MarkStatusEvent[];
+  versions: MarkVersions;
+}
+//#endregion
+//#region ../../apps/server/src/api/contracts.d.ts
+declare const legalDisclaimer = "Trademark data is informational, not legal advice. Verify critical decisions with the USPTO or qualified counsel.";
+interface AuthenticatedAccount {
+  accountId: string;
+  credential: {
+    type: "api-key";
+    keyId: string;
+    suffix: string;
+  } | {
+    type: "clerk";
+  };
+}
+interface PublicApiKey {
+  createdAt: string;
+  id: string;
+  lastUsedAt: string | null;
+  name: string;
+  status: "active" | "revoked";
+  suffix: string;
+}
+interface AccountService {
+  createApiKey: (name: string) => Promise<{
+    key: PublicApiKey;
+    token: string;
+  }>;
+  listApiKeys: () => Promise<PublicApiKey[]>;
+  revokeApiKey: (id: string) => Promise<PublicApiKey | null>;
+}
+type MarkDetail = Omit<ProjectedMark, "contributors" | "kind" | "mark" | "versions"> & {
+  legalDisclaimer: typeof legalDisclaimer;
+  mark: ProjectedMark["mark"] & {
+    status: "dead" | "live" | "unknown";
+  };
+  provenance: {
+    contributors: SourceContributor[];
+    versions: ProjectedMark["versions"];
+  };
+  type: MarkType;
+};
+interface SearchInputBase {
+  expectedDataVersion?: string;
+  limit: 25;
+  offset: number;
+  query: string;
+  registered: "all" | "yes" | "no";
+  sort: "relevance" | "newest-activity" | "oldest-activity";
+  status: "all" | "live" | "dead";
+  type: "all" | "design" | "typeset" | "text" | "other";
+}
+type SearchInput = SearchInputBase & ({
+  match: "exact" | "partial" | "both";
+  mode: "multi";
+} | {
+  match?: never;
+  mode: "split";
+} | {
+  match?: never;
+  mode: "wildcard";
+});
+interface MarkSummary {
+  goodsServicesExcerpt: string | null;
+  internationalClasses: string[];
+  owner: string | null;
+  registrationNumber: string | null;
+  serialNumber: string;
+  sourceTransactionDate: string | null;
+  status: "live" | "dead" | "unknown";
+  statusDate: string | null;
+  type: MarkType;
+  wordMark: string;
+}
+interface MarkPage {
+  items: MarkSummary[];
+  limit: 25;
+  meta: {
+    dataVersion: string;
+  };
+  offset: number;
+  total: number;
+}
+interface SearchPage extends Omit<MarkPage, "items"> {
+  items: Array<MarkSummary & {
+    match: "exact" | "partial";
+  }>;
+  liveMatchCounts: {
+    exact: number;
+    partial: number;
+  };
+}
+interface LatestInput {
+  expectedDataVersion?: string;
+  limit: 25;
+  offset: number;
+}
+interface MatchTextInput {
+  text: string;
+  type: "all" | "design" | "typeset" | "text" | "other";
+}
+interface MatchTextResult {
+  matches: Array<{
+    end: number;
+    mark: MarkSummary;
+    start: number;
+  }>;
+  meta: MarkPage["meta"];
+}
+interface MarksService {
+  getByRegistrationNumber: (registrationNumber: string) => Promise<MarkDetail | null>;
+  getBySerialNumber: (serialNumber: string) => Promise<MarkDetail | null>;
+  latest: (input: LatestInput) => Promise<MarkPage>;
+  matchText: (input: MatchTextInput) => Promise<MatchTextResult>;
+  search: (input: SearchInput) => Promise<SearchPage>;
+}
+interface ReportInput {
+  event: "filed" | "published-for-opposition" | "registered";
+  expectedDataVersion?: string;
+  expectedFrom?: string;
+  expectedTo?: string;
+  limit: 25;
+  offset: number;
+  registered: "all" | "yes" | "no";
+  sort: "newest-activity" | "oldest-activity";
+  status: "all" | "live" | "dead";
+  type: "all" | "design" | "typeset" | "text" | "other";
+  window?: "previous-week";
+}
+interface ReportPage extends MarkPage {
+  from: string | null;
+  items: Omit<SearchPage["items"][number], "match">[];
+  to: string | null;
+}
+interface ReportsService {
+  run: (input: ReportInput) => Promise<ReportPage>;
+}
+interface SyncStatus {
+  activeState: "applying" | "discovering" | "downloading" | "failed" | "idle";
+  dataVersion: number;
+  failedCount: number;
+  lastSuccessfulUpdateAt: string | null;
+  latestProcessedDate: string | null;
+  pendingCount: number;
+}
+interface SyncService {
+  status: () => Promise<SyncStatus>;
+}
+interface BoundedPage<T> {
+  items: T[];
+  limit: number;
+  offset: number;
+  total: number;
+}
+interface OperatorArtifact {
+  applicationCompletedAt: string | null;
+  applicationState: "applying" | "complete" | "needs_attention" | "pending";
+  appliedRecordCount: number;
+  artifactId: string;
+  bytes: number | null;
+  currentError: string | null;
+  downloadedAt: string | null;
+  downloadResponseState: {
+    contentLength?: string;
+    contentType?: string;
+    etag?: string;
+    observedAt?: string;
+    providerRequestCount?: number;
+    rateLimitReset?: string;
+    requestId?: string;
+    retryAfter?: string;
+    retryAfterSeconds?: number;
+    retryNotBefore?: string;
+    status: number;
+  } | null;
+  downloadState: "blocked" | "downloaded" | "downloading" | "pending";
+  filename: string;
+  parserVersion: string | null;
+  physicalRecordCount: number;
+  processingDisposition: "covered" | "deferred" | "required";
+  product: "TRTDXFAP" | "TRTYRAP";
+  projectedMarkCount: number;
+  sha256: string | null;
+  sourceFromDate: string;
+  sourceToDate: string;
+  storageState: "cleaned-up" | "not-downloaded" | "retained";
+  unresolvedRecordCount: number;
+  updatedAt: string;
+}
+interface OperatorPageInput {
+  limit: number;
+  offset: number;
+}
+interface PublicSourceStatus {
+  catalog: {
+    liveMarkCount: number;
+    registeredMarkCount: number;
+    totalMarkCount: number;
+  };
+  source: {
+    currentArtifact: {
+      filename: string;
+      state: "applying" | "discovering" | "downloading";
+    } | null;
+    lastActivityAt: string | null;
+    latestProcessedDate: string | null;
+    processingActivity: Array<{
+      count: number;
+      date: string;
+    }>;
+  };
+}
+interface OperatorSyncStatus extends PublicSourceStatus {
+  attention: {
+    items: Array<{
+      artifactId: string;
+      filename: string;
+      httpStatus: number | null;
+      message: string | null;
+      providerRequestCount: number | null;
+      retryNotBefore: string | null;
+      stage: "application" | "download" | "worker";
+      updatedAt: string;
+    }>;
+    total: number;
+  };
+}
+interface OperatorSyncService {
+  artifacts: (input: OperatorPageInput) => Promise<BoundedPage<OperatorArtifact>>;
+  publicStatus: () => Promise<PublicSourceStatus>;
+  status: () => Promise<OperatorSyncStatus>;
+}
+//#endregion
+//#region ../../apps/server/src/api/router.d.ts
+interface AppContext {
+  account: AccountService;
+  auth: AuthenticatedAccount;
+  marks: MarksService;
+  operator: boolean;
+  operatorSync: OperatorSyncService;
+  reports: ReportsService;
+  sync: SyncService;
+}
+declare const authenticatedClientRouter: import("@trpc/server").TRPCBuiltRouter<{
+  ctx: AppContext;
+  meta: object;
+  errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+  transformer: false;
+}, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+  account: import("@trpc/server").TRPCBuiltRouter<{
+    ctx: AppContext;
+    meta: object;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    transformer: false;
+  }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+    "api-keys": import("@trpc/server").TRPCBuiltRouter<{
+      ctx: AppContext;
+      meta: object;
+      errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+      transformer: false;
+    }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+      create: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+          name: string;
+        };
+        output: {
+          key: PublicApiKey;
+          token: string;
+        };
+        meta: object;
+      }>;
+      list: import("@trpc/server").TRPCQueryProcedure<{
+        input: void;
+        output: PublicApiKey[];
+        meta: object;
+      }>;
+      revoke: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+          id: string;
+        };
+        output: PublicApiKey;
+        meta: object;
+      }>;
+    }>>;
+    me: import("@trpc/server").TRPCQueryProcedure<{
+      input: void;
+      output: AuthenticatedAccount;
+      meta: object;
+    }>;
+  }>>;
+  marks: import("@trpc/server").TRPCBuiltRouter<{
+    ctx: AppContext;
+    meta: object;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    transformer: false;
+  }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+    get: import("@trpc/server").TRPCQueryProcedure<{
+      input: {
+        serialNumber: string;
+      };
+      output: MarkDetail;
+      meta: object;
+    }>;
+    "get-by-registration": import("@trpc/server").TRPCQueryProcedure<{
+      input: {
+        registrationNumber: string;
+      };
+      output: MarkDetail;
+      meta: object;
+    }>;
+    latest: import("@trpc/server").TRPCQueryProcedure<{
+      input: {
+        expectedDataVersion?: string | undefined;
+        limit?: 25 | undefined;
+        offset?: number | undefined;
+      };
+      output: MarkPage;
+      meta: object;
+    }>;
+    "match-text": import("@trpc/server").TRPCQueryProcedure<{
+      input: {
+        text: string;
+        type?: "all" | "design" | "other" | "text" | "typeset" | undefined;
+      };
+      output: MatchTextResult;
+      meta: object;
+    }>;
+    search: import("@trpc/server").TRPCQueryProcedure<{
+      input: {
+        expectedDataVersion?: string | undefined;
+        limit?: 25 | undefined;
+        offset?: number | undefined;
+        query: string;
+        registered?: "all" | "no" | "yes" | undefined;
+        sort?: "newest-activity" | "oldest-activity" | "relevance" | undefined;
+        status?: "all" | "dead" | "live" | undefined;
+        type?: "all" | "design" | "other" | "text" | "typeset" | undefined;
+        match?: "both" | "exact" | "partial" | undefined;
+        mode: "multi";
+      } | {
+        expectedDataVersion?: string | undefined;
+        limit?: 25 | undefined;
+        offset?: number | undefined;
+        query: string;
+        registered?: "all" | "no" | "yes" | undefined;
+        sort?: "newest-activity" | "oldest-activity" | "relevance" | undefined;
+        status?: "all" | "dead" | "live" | undefined;
+        type?: "all" | "design" | "other" | "text" | "typeset" | undefined;
+        match?: undefined;
+        mode: "split";
+      } | {
+        expectedDataVersion?: string | undefined;
+        limit?: 25 | undefined;
+        offset?: number | undefined;
+        query: string;
+        registered?: "all" | "no" | "yes" | undefined;
+        sort?: "newest-activity" | "oldest-activity" | "relevance" | undefined;
+        status?: "all" | "dead" | "live" | undefined;
+        type?: "all" | "design" | "other" | "text" | "typeset" | undefined;
+        match?: undefined;
+        mode: "wildcard";
+      };
+      output: SearchPage;
+      meta: object;
+    }>;
+  }>>;
+  reports: import("@trpc/server").TRPCBuiltRouter<{
+    ctx: AppContext;
+    meta: object;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    transformer: false;
+  }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+    run: import("@trpc/server").TRPCQueryProcedure<{
+      input: {
+        expectedDataVersion?: string | undefined;
+        limit?: 25 | undefined;
+        offset?: number | undefined;
+        registered?: "all" | "no" | "yes" | undefined;
+        sort?: "newest-activity" | "oldest-activity" | undefined;
+        status?: "all" | "dead" | "live" | undefined;
+        type?: "all" | "design" | "other" | "text" | "typeset" | undefined;
+        expectedFrom?: string | undefined;
+        expectedTo?: string | undefined;
+        event: "filed";
+        window: "previous-week";
+      } | {
+        expectedDataVersion?: string | undefined;
+        limit?: 25 | undefined;
+        offset?: number | undefined;
+        registered?: "all" | "no" | "yes" | undefined;
+        sort?: "newest-activity" | "oldest-activity" | undefined;
+        status?: "all" | "dead" | "live" | undefined;
+        type?: "all" | "design" | "other" | "text" | "typeset" | undefined;
+        expectedFrom?: string | undefined;
+        expectedTo?: string | undefined;
+        event: "registered";
+        window: "previous-week";
+      } | {
+        expectedDataVersion?: string | undefined;
+        limit?: 25 | undefined;
+        offset?: number | undefined;
+        registered?: "all" | "no" | "yes" | undefined;
+        sort?: "newest-activity" | "oldest-activity" | undefined;
+        status?: "all" | "dead" | "live" | undefined;
+        type?: "all" | "design" | "other" | "text" | "typeset" | undefined;
+        event: "published-for-opposition";
+      };
+      output: ReportPage;
+      meta: object;
+    }>;
+  }>>;
+  sync: import("@trpc/server").TRPCBuiltRouter<{
+    ctx: AppContext;
+    meta: object;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    transformer: false;
+  }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+    status: import("@trpc/server").TRPCQueryProcedure<{
+      input: void;
+      output: SyncStatus;
+      meta: object;
+    }>;
+  }>>;
+}>>;
+type AuthenticatedClientRouter = typeof authenticatedClientRouter;
+//#endregion
+//#region src/index.d.ts
+type InternalClient = CreateTRPCClient<AuthenticatedClientRouter>;
+type InternalInputs = inferRouterInputs<AuthenticatedClientRouter>;
+type InternalOutputs = inferRouterOutputs<AuthenticatedClientRouter>;
+interface TmturtleClient {
+  account: InternalClient["account"];
+  reports: InternalClient["reports"];
+  status: InternalClient["sync"]["status"];
+  trademarks: {
+    get: InternalClient["marks"]["get"];
+    getByRegistration: InternalClient["marks"]["get-by-registration"];
+    latest: InternalClient["marks"]["latest"];
+    matchText: InternalClient["marks"]["match-text"];
+    search: InternalClient["marks"]["search"];
+  };
+}
+interface TmturtleRouterInputs {
+  account: InternalInputs["account"];
+  reports: InternalInputs["reports"];
+  status: InternalInputs["sync"]["status"];
+  trademarks: {
+    get: InternalInputs["marks"]["get"];
+    getByRegistration: InternalInputs["marks"]["get-by-registration"];
+    latest: InternalInputs["marks"]["latest"];
+    matchText: InternalInputs["marks"]["match-text"];
+    search: InternalInputs["marks"]["search"];
+  };
+}
+interface TmturtleRouterOutputs {
+  account: InternalOutputs["account"];
+  reports: InternalOutputs["reports"];
+  status: InternalOutputs["sync"]["status"];
+  trademarks: {
+    get: InternalOutputs["marks"]["get"];
+    getByRegistration: InternalOutputs["marks"]["get-by-registration"];
+    latest: InternalOutputs["marks"]["latest"];
+    matchText: InternalOutputs["marks"]["match-text"];
+    search: InternalOutputs["marks"]["search"];
+  };
+}
+interface TmturtleClientOptions {
+  apiKey: string;
+  baseUrl: string;
+}
+declare function createTmturtleClient({ apiKey, baseUrl }: TmturtleClientOptions): TmturtleClient;
+//#endregion
+export { TmturtleClient, TmturtleClientOptions, TmturtleRouterInputs, TmturtleRouterOutputs, createTmturtleClient };

package/dist/index.mjs

@@ -0,0 +1,22 @@
+import { createTRPCClient, httpLink } from "@trpc/client";
+//#region src/index.ts
+function createTmturtleClient({ apiKey, baseUrl }) {
+	const client = createTRPCClient({ links: [httpLink({
+		headers: { authorization: `Bearer ${apiKey}` },
+		url: new URL("/api/trpc", baseUrl).toString()
+	})] });
+	return {
+		account: client.account,
+		reports: client.reports,
+		status: client.sync.status,
+		trademarks: {
+			get: client.marks.get,
+			getByRegistration: client.marks["get-by-registration"],
+			latest: client.marks.latest,
+			matchText: client.marks["match-text"],
+			search: client.marks.search
+		}
+	};
+}
+//#endregion
+export { createTmturtleClient };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@tmturtle/http-client",
+  "version": "1.0.0",
+  "description": "Typed HTTP client for the Trademark Turtle API",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/merchbaseco/tmturtle.git",
+    "directory": "packages/http-client"
+  },
+  "homepage": "https://github.com/merchbaseco/tmturtle#readme",
+  "bugs": "https://github.com/merchbaseco/tmturtle/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@trpc/client": "11.18.0",
+    "@trpc/server": "11.18.0"
+  },
+  "devDependencies": {
+    "tsdown": "0.22.8"
+  }
+}