humanizedtext 0.1.0 → 0.1.2

package/README.md

@@ -1,36 +1,261 @@
 # humanizedtext (npm)
 
-Official JavaScript SDK for HumanizedText API.
+Official JavaScript SDK for the HumanizedText API.
 
-## Install
+This SDK wraps the authenticated SDK endpoints exposed by HumanizedText and provides:
+
+- API key authentication via `X-API-Key`
+- Request timeout handling
+- Typed runtime errors (`HumanizedTextAPIError`)
+- Clean methods for humanize, grammar fix, rewrite, and SEO blog writing
+
+## Contents
+
+1. Requirements
+2. Installation
+3. Authentication
+4. Client Configuration
+5. API Methods
+6. Response Examples
+7. Error Handling
+8. Edge Cases and Limits
+9. Production Recommendations
+
+## Requirements
+
+- Node.js `>=18`
+- A valid HumanizedText API key
+
+## Installation
 
 ```bash
 npm install humanizedtext
 ```
 
-## Quick Start
+## Authentication
+
+The SDK sends your key in the `X-API-Key` header.
+
+Generate/manage your key from your HumanizedText dashboard, then initialize the client with it.
 
 ```js
 const { HumanizedTextClient } = require("humanizedtext");
 
+const client = new HumanizedTextClient({
+  apiKey: process.env.HUMANIZEDTEXT_API_KEY,
+});
+```
+
+## Client Configuration
+
+```js
 const client = new HumanizedTextClient({
   apiKey: "YOUR_API_KEY",
   baseUrl: "https://api.humanizedtext.pro/api/v1",
+  timeout: 60000,
 });
+```
+
+| Option    | Type     | Required | Default                                | Description                     |
+| --------- | -------- | -------- | -------------------------------------- | ------------------------------- |
+| `apiKey`  | `string` | Yes      | -                                      | HumanizedText API key           |
+| `baseUrl` | `string` | No       | `https://api.humanizedtext.pro/api/v1` | API base URL                    |
+| `timeout` | `number` | No       | `60000`                                | Request timeout in milliseconds |
 
-const result = await client.humanize({
-  text: "This is a sample text.",
+## API Methods
+
+### 1) `humanize(params)`
+
+Humanizes input text with optional tone, keyword insertion, and ultra mode.
+
+```js
+const res = await client.humanize({
+  text: "Your AI-like text here",
   tone: "professional",
-  ultraHumanize: true,
-  keywords: ["SEO", "AI writing"],
+  ultraHumanize: false,
+  keywords: ["SaaS", "conversion"],
 });
+```
+
+| Param           | Type               | Required | Default | Notes                                                    |
+| --------------- | ------------------ | -------- | ------- | -------------------------------------------------------- |
+| `text`          | `string`           | Yes      | -       | Must be `1..6000` characters                             |
+| `tone`          | `string \| null`   | No       | `null`  | Example: `professional`, `casual`, `friendly`, `default` |
+| `ultraHumanize` | `boolean`          | No       | `false` | Uses ultra quota per request when `true`                 |
+| `keywords`      | `string[] \| null` | No       | `null`  | Plan-limited count per request                           |
+
+### 2) `grammarFixer(params)`
+
+Fixes grammar while preserving meaning.
+
+```js
+const res = await client.grammarFixer({ text: "this are a sentence." });
+```
+
+| Param  | Type     | Required | Notes                        |
+| ------ | -------- | -------- | ---------------------------- |
+| `text` | `string` | Yes      | Must be `1..6000` characters |
+
+### 3) `contentRewriter(params)`
+
+Rewrites content to improve readability/originality.
+
+```js
+const res = await client.contentRewriter({
+  text: "Original paragraph to rewrite",
+});
+```
+
+| Param  | Type     | Required | Notes                        |
+| ------ | -------- | -------- | ---------------------------- |
+| `text` | `string` | Yes      | Must be `1..6000` characters |
+
+### 4) `seoBlogWriter(params)`
+
+Generates SEO-focused blog content from a topic.
+
+```js
+const res = await client.seoBlogWriter({
+  topic: "Best CRM tools for startups",
+});
+```
 
-console.log(result);
+| Param   | Type     | Required | Notes                       |
+| ------- | -------- | -------- | --------------------------- |
+| `topic` | `string` | Yes      | Must be `1..500` characters |
+
+## Response Examples
+
+Actual responses are JSON objects. Common shapes:
+
+### Humanize response
+
+```json
+{
+  "original_text": "Your original text",
+  "humanized_text": "Humanized output text",
+  "tone_applied": "professional",
+  "ultra_humanize_used": false,
+  "keywords_used": ["SaaS", "conversion"],
+  "created_at": "2026-04-12T15:20:11.891000+00:00"
+}
 ```
 
-## Methods
+### Grammar fixer response
+
+```json
+{
+  "original_text": "this are a sentence.",
+  "corrected_text": "This is a sentence.",
+  "created_at": "2026-04-12T15:21:17.003000+00:00"
+}
+```
+
+### Content rewriter response
+
+```json
+{
+  "original_text": "Old copy here",
+  "rewritten_text": "Rewritten copy here",
+  "created_at": "2026-04-12T15:22:40.221000+00:00"
+}
+```
+
+### SEO blog writer response
+
+```json
+{
+  "topic": "Best CRM tools for startups",
+  "blog_content": "# Best CRM tools for startups\n...",
+  "created_at": "2026-04-12T15:23:35.552000+00:00"
+}
+```
+
+## Error Handling
+
+The SDK throws `HumanizedTextAPIError` for HTTP failures.
+
+```js
+const { HumanizedTextClient, HumanizedTextAPIError } = require("humanizedtext");
+
+try {
+  await client.humanize({ text: "" });
+} catch (err) {
+  if (err instanceof HumanizedTextAPIError) {
+    console.error("status:", err.statusCode);
+    console.error("payload:", err.payload);
+  } else {
+    console.error("unexpected:", err);
+  }
+}
+```
+
+`HumanizedTextAPIError` fields:
+
+| Field        | Type                  | Description            |
+| ------------ | --------------------- | ---------------------- |
+| `message`    | `string`              | Error detail string    |
+| `statusCode` | `number \| undefined` | HTTP status code       |
+| `payload`    | `unknown`             | Raw parsed API payload |
+
+## Edge Cases and Limits
+
+### Text length
+
+- `text` must be `1..6000` chars for humanize/grammar/rewrite.
+- `topic` must be `1..500` chars for SEO blog writer.
+
+Typical failure: `400 Bad Request`.
+
+### Invalid API key
+
+Typical failure: `401 Unauthorized`.
+
+### Plan character quota exceeded
+
+Typical failure: `402 Payment Required`.
+`detail` may be an object like:
+
+```json
+{
+  "message": "SDK character limit exceeded for current period",
+  "plan": "free",
+  "characters_needed": 1200,
+  "remaining_characters": 0,
+  "period_resets_at": "2026-04-30T00:00:00+00:00"
+}
+```
+
+### Ultra mode quota exceeded
+
+Typical failure: `429 Too Many Requests` with remaining ultra count.
+
+### Keywords per request limit exceeded
+
+Typical failure: `400 Bad Request`.
+`detail` may include:
+
+```json
+{
+  "message": "Keyword limit exceeded",
+  "max_keywords_allowed": 1,
+  "keywords_provided": 3,
+  "upgrade_required": true
+}
+```
+
+### Timeout and network failures
+
+- The SDK aborts after `timeout` milliseconds.
+- Network failures are thrown as native runtime errors.
+
+## Production Recommendations
+
+- Store API keys in environment variables, never hardcode them.
+- Implement retry with exponential backoff for transient 5xx or network errors.
+- Log `statusCode` and `payload` from `HumanizedTextAPIError` for observability.
+- Validate and trim user input before sending to avoid avoidable 400s.
+
+## License
 
-- `humanize({ text, tone, ultraHumanize, keywords })`
-- `grammarFixer({ text })`
-- `contentRewriter({ text })`
-- `seoBlogWriter({ topic })`
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanizedtext",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Official JavaScript SDK for HumanizedText API",
   "main": "index.js",
   "types": "index.d.ts",