@minimist/client-ts

TypeScript gRPC client library for Minimist APIs. This package provides fully typed clients generated from protobuf definitions using Buf and Connect-ES.

Installation

# Using pnpm (recommended)
pnpm add @minimistapp/client-ts

# Using npm
npm install @minimistapp/client-ts

# Using yarn
yarn add @minimistapp/client-ts

Quick Start

Basic Setup

import { createClient } from "@connectrpc/connect";
import {
  createTransport,
  PredictorService,
} from "@minimistapp/client-ts";

// Get an access token from your authentication service
async function getAccessToken() {
  // Implement your token retrieval logic here
  return "your-access-token";
}

// Create a transport with authentication (preferred: no side effects)
const transport = createTransport({
  getAccessToken,
  // Optional overrides:
  // baseUrl: process.env.MINIMIST_API_URL ?? "https://api-grpc.mnm.st",
  // defaultTimeoutMs: 30000,
});

// Create a client
const client = createClient(PredictorService, transport);

Example: Predict Category from Images

import { createClient } from "@connectrpc/connect";
import { create } from "@bufbuild/protobuf";
import { 
  createTransport,
  PredictorService,
  PredictCategoryRequestSchema,
  PredictCategoryResponse
} from "@minimistapp/client-ts";

async function getAccessToken() {
  // Implement your token retrieval logic here
  return "your-access-token";
}

async function predictCategory() {
  // Setup client
  const transport = createTransport({ getAccessToken });
  const client = createClient(PredictorService, transport);

  // Prepare request (recommended): use the schema-aware create() helper
  const request = create(PredictCategoryRequestSchema, {
    listingId: "listing_123",
    imageUrls: [
      "https://example.com/product-image-1.jpg",
      "https://example.com/product-image-2.jpg"
    ],
    storeId: "store_456", // deprecated but kept for compatibility
    tenantId: "tenant_789"
  });

  try {
    // Make the API call
    const response = await client.predictCategory(request);

    // response is of type `PredictCategoryResponse`
    return response;
  } catch (error) {
    console.error("Failed to predict category:", error);
    throw error;
  }
}

Creating request messages with create()

All request/response messages come with a generated *Schema that can be used with create() from @bufbuild/protobuf. Benefits:

• Strong typing guided by the schema at compile-time
• Default values are applied (e.g. empty arrays/strings)
• Nested messages and oneof fields are easy to construct

import { create } from "@bufbuild/protobuf";
import {
  PredictCategoryRequestSchema,
  PredictCategoryByAttributesRequestSchema,
  PredictCategoryByAttributesRequest_ProvidedAttributeSchema,
  SessionContextSchema,
  AttributePredictedSchema,
} from "@minimistapp/client-ts";

// Basic request
const req = create(PredictCategoryRequestSchema, {
  listingId: "abc",
  imageUrls: ["https://example.com/img.jpg"],
});

// With optional session context
const session = create(SessionContextSchema, {
  userId: "user_123",
  locale: "en-US",
});
const reqWithContext = create(PredictCategoryRequestSchema, {
  listingId: "abc",
  imageUrls: ["https://example.com/img.jpg"],
  sessionContext: session,
});

// PredictCategoryByAttributes with a oneof ProvidedAttribute
const providedAttribute = create(
  PredictCategoryByAttributesRequest_ProvidedAttributeSchema,
  {
    attribute: {
      case: "attributePrediction",
      value: create(AttributePredictedSchema, {
        // fill predicted attribute fields here
      }),
    },
  },
);

const byAttributes = create(PredictCategoryByAttributesRequestSchema, {
  attributes: [providedAttribute],
});

Using a singleton transport (optional)

Prefer createTransport() for a new, side-effect-free transport per call. If you need to share a single instance across your app, you can use getTransport() which caches the first created transport:

import { getTransport } from "@minimistapp/client-ts";

const transport = getTransport({ getAccessToken });
// Subsequent calls to getTransport() will return the same instance

In-memory testing

You can test your client without a running server by using an in-memory router transport. This is ideal for unit tests and does not perform network I/O.

import { createClient, createRouterTransport, ConnectError, Code } from "@connectrpc/connect";
import { create } from "@bufbuild/protobuf";
import {
  PredictorService,
  PredictCategoryRequestSchema,
  PredictCategoryResponseSchema,
} from "@minimistapp/client-ts";

// Define in-memory routes for tests
const transport = createRouterTransport(({ service }) => {
  service(PredictorService, {
    async predictCategory(req) {
      // You can add assertions here in your tests
      return create(PredictCategoryResponseSchema, {
        listingId: req.listingId,
      });
    },
  });
});

// Use your normal client with the in-memory transport
const client = createClient(PredictorService, transport);
const res = await client.predictCategory(
  create(PredictCategoryRequestSchema, {
    listingId: "listing-1",
    imageUrls: ["https://example/img.jpg"],
  })
);

// Example: Raising a ConnectError in a route
createRouterTransport(({ service }) => {
  service(PredictorService, {
    predictCategory() {
      throw new ConnectError("invalid", Code.InvalidArgument);
    },
  });
});

Error Handling

import { ConnectError, Code } from "@connectrpc/connect";

try {
  const response = await client.yourMethod(request);
} catch (err) {
  if (err instanceof ConnectError) {
    switch (err.code) {
      case Code.NotFound:
        console.log("Resource not found");
        break;
      case Code.Unauthenticated:
        console.log("Authentication required");
        break;
      default:
        console.log(`gRPC error: ${err.message}`);
    }
  }
}