This toolkit provides a type-safe way to interact with Markup AI services including style analysis, style guide management, and batch operations.
npm install @markupai/toolkitThe toolkit supports string content, File objects, and Buffer objects for style analysis with automatic MIME type detection for binary files. It also supports HTML content strings and files:
import {
// Auto-polling convenience methods
styleCheck,
styleSuggestions,
styleRewrite,
// Async workflow helpers
submitStyleCheck,
submitStyleSuggestion,
submitStyleRewrite,
getStyleCheck,
getStyleSuggestion,
getStyleRewrite,
} from "@markupai/toolkit";
// Using string content
const stringRequest = {
content: "This is a sample text for style analysis.",
style_guide: "ap",
dialect: "american_english",
tone: "formal",
};
// Using HTML string content (auto-detected as text/html)
const htmlStringRequest = {
content: "<!doctype html><html><body><p>Hello</p></body></html>",
style_guide: "ap",
dialect: "american_english",
tone: "formal",
// Optional: provide a filename to enforce MIME type
documentNameWithExtension: "page.html",
};
// Using File object (browser environments)
const file = new File(["This is content from a file."], "document.txt", { type: "text/plain" });
const fileRequest = {
content: { file }, // FileDescriptor (optionally add mimeType)
style_guide: "chicago",
dialect: "american_english",
tone: "academic",
};
// Using BufferDescriptor (Node.js environments) - BINARY FILES SUPPORTED
const fs = require("fs");
const pdfBuffer = fs.readFileSync("technical-report.pdf");
const bufferRequest = {
content: {
buffer: pdfBuffer,
mimeType: "application/pdf",
documentNameWithExtension: "technical-report.pdf",
},
style_guide: "ap",
dialect: "american_english",
tone: "academic",
};
// Perform style analysis with polling (convenience)
const result = await styleCheck(stringRequest, config);
const fileResult = await styleCheck(fileRequest, config);
const pdfResult = await styleCheck(bufferRequest, config); // Works with PDFs!
const htmlResult = await styleCheck(htmlStringRequest, config); // Works with HTML!
// Get style suggestions
const suggestionResult = await styleSuggestions(stringRequest, config);
// Get style rewrites
const rewriteResult = await styleRewrite(stringRequest, config);For processing multiple documents efficiently, the toolkit provides batch operations:
import {
styleBatchCheckRequests,
styleBatchSuggestions,
styleBatchRewrites,
} from "@markupai/toolkit";
const requests = [
{
content: "First document content",
style_guide: "ap",
dialect: "american_english",
tone: "formal",
},
{
content: "Second document content",
style_guide: "chicago",
dialect: "american_english",
tone: "academic",
},
// ... more requests
];
// Batch style checks
const batchCheck = styleBatchCheckRequests(requests, config, {
maxConcurrent: 5,
retryAttempts: 3,
retryDelay: 1_000,
timeoutMillis: 30_000,
});
// Monitor progress (live snapshot)
console.log(`Started: total ${batchCheck.progress.total}`);
const interval = setInterval(() => {
const p = batchCheck.progress;
console.log(
`Progress: ${p.completed}/${p.total} completed, ${p.inProgress} in-progress, ${p.failed} failed`,
);
if (p.completed + p.failed === p.total) clearInterval(interval);
}, 1_000);
// Await final results
batchCheck.promise.then((finalProgress) => {
console.log(`Completed: ${finalProgress.completed}/${finalProgress.total}`);
console.log(`Failed: ${finalProgress.failed}`);
for (const [index, result] of finalProgress.results.entries()) {
if (result.status === "completed") {
console.log(`Request ${index}: ${result.result?.original.scores.quality.score}`);
} else if (result.status === "failed") {
console.log(`Request ${index} failed: ${result.error?.message}`);
}
}
});
// Batch suggestions
const batchSuggestions = styleBatchSuggestions(requests, config);
// Batch rewrites
const batchRewrites = styleBatchRewrites(requests, config);
// Cancel batch operations if needed
batchCheck.cancel();The toolkit provides comprehensive response types for different operations:
import type {
StyleAnalysisSuccessResp,
StyleAnalysisSuggestionResp,
StyleAnalysisRewriteResp,
StyleScores,
Issue,
IssueWithSuggestion,
} from "@markupai/toolkit";
// Style check response
const checkResult: StyleAnalysisSuccessResp = await styleCheck(request, config);
console.log(`Quality score: ${checkResult.original.scores.quality.score}`);
console.log(`Issues found: ${checkResult.original.issues.length}`);
// Style suggestion response
const suggestionResult: StyleAnalysisSuggestionResp = await styleSuggestions(request, config);
for (const issue of suggestionResult.original.issues) {
console.log(`Issue: "${issue.original}" → Suggestion: "${issue.suggestion}"`);
}
// Style rewrite response
const rewriteResult: StyleAnalysisRewriteResp = await styleRewrite(request, config);
console.log(`Rewritten content: ${rewriteResult.rewrite.text}`);
console.log(`Rewrite quality score: ${rewriteResult.rewrite.scores.quality.score}`);The toolkit requires a configuration object with your API key and platform settings:
import { Config, Environment, PlatformType } from "@markupai/toolkit";
// Using environment-based configuration
const config: Config = {
apiKey: "your-api-key-here",
platform: {
type: PlatformType.Environment,
value: Environment.Prod, // or Environment.Stage, Environment.Dev
},
};
// Using custom URL configuration
const configWithUrl: Config = {
apiKey: "your-api-key-here",
platform: {
type: PlatformType.Url,
value: "https://api.dev.markup.ai",
},
};- Node.js (Latest LTS version recommended)
- npm
- Clone the repository:
git clone https://github.com/markupai/toolkit
cd toolkit- Install dependencies:
npm installTo build the project:
npm run buildThis will:
- Compile TypeScript files
- Generate type definitions
- Create both ESM and UMD bundles
The project uses Vitest for testing. There are two types of tests:
- Unit Tests: Located in
test/unit/ - Integration Tests: Located in
test/integration/
To run all tests:
npm testTo run unit tests only:
npm run test:unitTo run integration tests only:
npm run test:integrationThe project includes linting and formatting tools:
# Lint the code
npm run lint
# Fix linting issues
npm run lint:fix
# Format code with Prettier
npm run formatThis project is licensed under the Apache-2.0 License - see the LICENSE file for details.