parasut-node-sdk-mcp 1.0.0

package/.github/workflows/deploy.yaml

@@ -0,0 +1,51 @@
+name: "Publish Parasut API Docs to GitHub Pages"
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+      - run: npm ci
+      - run: npm run build
+      - name: Compress artifact
+        run: |
+          chmod -c -R +rX "web_deploy" | while read line; do
+            echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+          tar \
+            --dereference \
+            --directory "web_deploy" \
+            -cvf "artifact.tar" \
+            .
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: 'github-pages'
+          path: artifact.tar
+          retention-days: 1
+          if-no-files-found: error
+  deploy:
+    needs: build
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,71 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [main]
+    paths-ignore: ['*.md', 'docs/**', 'LICENSE', '.gitignore']
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: 'Version bump type'
+        required: false
+        type: choice
+        default: patch
+        options: [patch, minor, major]
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - run: npm install
+
+      - run: npm run build
+
+      - name: Check if version exists on npm
+        id: check
+        run: |
+          PKG_NAME=$(node -p "require('./package.json').name")
+          PKG_VER=$(node -p "require('./package.json').version")
+          echo "name=$PKG_NAME version=$PKG_VER"
+          set +e
+          npm view "${PKG_NAME}@${PKG_VER}" version 2>/dev/null
+          if [ $? -eq 0 ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Bump version
+        id: bump
+        if: steps.check.outputs.exists == 'true' && github.actor != 'github-actions[bot]'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          BUMP="${{ inputs.bump || 'patch' }}"
+          npm version "$BUMP" -m "chore: bump to v%s [skip ci]"
+          git push && git push --tags
+          echo "bumped=true" >> "$GITHUB_OUTPUT"
+
+      - name: Rebuild after bump
+        if: steps.bump.outputs.bumped == 'true'
+        run: npm run build
+
+      - name: Publish to npm
+        if: steps.check.outputs.exists == 'false' || steps.bump.outputs.bumped == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

package/.travis.yml

@@ -0,0 +1,15 @@
+language: node_js
+node_js:
+  - "node"
+deploy:
+  - skip_cleanup: true
+    provider: script
+    script: npm run deploy
+    on:
+      branch: master
+  - skip_cleanup: true
+    provider: script
+    script: npm run deploy-branch
+    on:
+      all_branches: true
+      condition: '"$TRAVIS_BRANCH" != "master" && "$TRAVIS_BRANCH" != "gh-pages"'

package/.yo-rc.json

@@ -0,0 +1,11 @@
+{
+  "generator-openapi-repo": {
+    "importExistingSpec": true,
+    "importedSpec": "/Users/furkan/parasut/swagger/out/v4/v4.yaml",
+    "name": "Parasut API",
+    "repo": "parasutcom/api-doc",
+    "splitSpec": false,
+    "samples": true,
+    "installSwaggerUI": false
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Ivan Goncharov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# Paraşüt Node.js SDK & MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@yigitkonur/parasut-node-sdk.svg)](https://www.npmjs.com/package/@yigitkonur/parasut-node-sdk)
+[![npm version](https://img.shields.io/npm/v/@yigitkonur/parasut-mcp-server.svg)](https://www.npmjs.com/package/@yigitkonur/parasut-mcp-server)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **UNOFFICIAL** TypeScript SDK and MCP (Model Context Protocol) Server for the [Paraşüt](https://www.parasut.com/) API v4.
+>
+> **This project is not affiliated with, endorsed by, or connected to Paraşüt in any way.**
+
+A monorepo containing two packages for Turkish accounting and e-invoicing:
+
+| Package | Description | Install |
+|---------|-------------|---------|
+| **[@yigitkonur/parasut-node-sdk](./packages/parasut-node-sdk)** | Type-safe TypeScript SDK | `npm i @yigitkonur/parasut-node-sdk` |
+| **[@yigitkonur/parasut-mcp-server](./packages/parasut-mcp-server)** | MCP Server for Claude AI | `npm i -g @yigitkonur/parasut-mcp-server` |
+
+## Features
+
+### SDK Features
+
+- **100% Type-Safe** - Full TypeScript with maximum strict mode
+- **Complete API Coverage** - All Paraşüt v4 endpoints
+- **OAuth 2.0** - Automatic token refresh
+- **Rate Limiting** - Built-in token bucket (10 req/10s)
+- **Retry Logic** - Exponential backoff for transient errors
+- **Zero Dependencies** - Uses native `fetch` (Node.js 18+)
+- **JSON:API Compliant** - Proper request/response handling
+
+### MCP Server Features
+
+- **34 AI-Optimized Tools** - Intent-first design, not 1:1 API mapping
+- **Confirmation Patterns** - Preview mode for financial operations
+- **Double Confirmation** - Extra safety for irreversible e-document submissions
+- **Smart Responses** - Next-step guidance and recovery instructions
+- **Turkish E-Invoicing** - e-Fatura, e-Arşiv, e-SMM support
+
+## Quick Start
+
+### SDK Usage
+
+```bash
+npm install @yigitkonur/parasut-node-sdk
+```
+
+```typescript
+import { ParasutClient } from '@yigitkonur/parasut-node-sdk';
+
+const client = new ParasutClient({
+  companyId: 123456,
+  credentials: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    username: 'your-username',
+    password: 'your-password',
+  },
+});
+
+// List all customers
+const { data: contacts } = await client.contacts.list({
+  filter: { account_type: 'customer' },
+});
+
+// Create an invoice
+const { data: invoice } = await client.salesInvoices.create({
+  data: {
+    type: 'sales_invoices',
+    attributes: {
+      item_type: 'invoice',
+      issue_date: '2024-01-15',
+      currency: 'TRL',
+    },
+    relationships: {
+      contact: { data: { id: '12345', type: 'contacts' } },
+    },
+  },
+});
+```
+
+### MCP Server Usage
+
+```bash
+npm install -g @yigitkonur/parasut-mcp-server
+```
+
+Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "parasut": {
+      "command": "parasut-mcp",
+      "env": {
+        "PARASUT_COMPANY_ID": "123456",
+        "PARASUT_CLIENT_ID": "your-client-id",
+        "PARASUT_CLIENT_SECRET": "your-client-secret",
+        "PARASUT_USERNAME": "your-username",
+        "PARASUT_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+Then ask Claude:
+
+> "Show me all unpaid invoices from this month"
+>
+> "Create an invoice for 5000 TL consulting services to Acme Corp"
+>
+> "Send invoice #1234 as e-fatura"
+
+## Supported Operations
+
+| Category | Operations |
+|----------|------------|
+| **Contacts** | Search, create, update customers/suppliers |
+| **Sales Invoices** | Create, cancel, recover, record payments, generate PDF |
+| **Purchase Bills** | Create expenses, record supplier payments |
+| **Products** | Manage products and services catalog |
+| **E-Documents** | e-Fatura, e-Arşiv, e-SMM (with double confirmation) |
+| **Financial** | Accounts, transactions, bank fees |
+| **Inventory** | Stock levels and movements |
+| **Organization** | Categories, tags, employees, salaries, taxes |
+
+## TypeScript Strictness
+
+Both packages use maximum TypeScript strictness:
+
+```
+strict: true
+exactOptionalPropertyTypes: true
+noUncheckedIndexedAccess: true
+noPropertyAccessFromIndexSignature: true
+noImplicitOverride: true
++ 15 more strict checks
+```
+
+## Requirements
+
+- **Node.js** >= 18.0.0
+- **Paraşüt API Credentials** (OAuth 2.0)
+
+## Getting API Credentials
+
+1. Log in to [Paraşüt](https://app.parasut.com)
+2. Go to **Settings → API → Applications**
+3. Create a new application
+4. Note your **Client ID** and **Client Secret**
+5. Your **Company ID** is in the URL: `app.parasut.com/{COMPANY_ID}/...`
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/yigitkonur/parasut-node-sdk-mcp.git
+cd parasut-node-sdk-mcp
+
+# Install
+npm install
+
+# Build all
+npm run build
+
+# Type check
+npm run typecheck
+```
+
+## Disclaimer
+
+**This is an UNOFFICIAL project.**
+
+- Not affiliated with, endorsed by, or connected to Paraşüt
+- Paraşüt is a trademark of Paraşüt Bilgi Teknolojileri A.Ş.
+- Use at your own risk
+- The maintainers are not responsible for any issues arising from use
+
+## License
+
+MIT © [Yigit Konur](https://github.com/yigitkonur)
+
+## Links
+
+- [Paraşüt API Documentation](https://apidocs.parasut.com/)
+- [MCP Protocol](https://modelcontextprotocol.io/)
+- [Report Issues](https://github.com/yigitkonur/parasut-node-sdk-mcp/issues)

package/gulpfile.js

@@ -0,0 +1,50 @@
+var gulp = require('gulp');
+var util = require('gulp-util')
+var gulpConnect = require('gulp-connect');
+var connect = require('connect');
+var cors = require('cors');
+var path = require('path');
+var exec = require('child_process').exec;
+var portfinder = require('portfinder');
+var swaggerRepo = require('swagger-repo');
+
+var DIST_DIR = 'web_deploy';
+
+gulp.task('serve', ['build', 'watch', 'edit'], function() {
+  portfinder.getPort({port: 3000}, function (err, port) {
+    gulpConnect.server({
+      root: [DIST_DIR],
+      livereload: true,
+      port: port,
+      middleware: function (gulpConnect, opt) {
+        return [
+          cors()
+        ]
+      }
+    });
+  });
+});
+
+gulp.task('edit', function() {
+  portfinder.getPort({port: 5000}, function (err, port) {
+    var app = connect();
+    app.use(swaggerRepo.swaggerEditorMiddleware());
+    app.listen(port);
+    util.log(util.colors.green('swagger-editor started http://localhost:' + port));
+  });
+});
+
+gulp.task('build', function (cb) {
+  exec('npm run build', function (err, stdout, stderr) {
+    console.log(stderr);
+    cb(err);
+  });
+});
+
+gulp.task('reload', ['build'], function () {
+  gulp.src(DIST_DIR).pipe(gulpConnect.reload())
+});
+
+gulp.task('watch', function () {
+  gulp.watch(['spec/**/*', 'web/**/*'], ['reload']);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "parasut-node-sdk-mcp",
+  "version": "1.0.0",
+  "description": "Unofficial TypeScript SDK and MCP Server for Para\u015f\u00fct API - Turkish accounting and e-invoicing",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "build:sdk": "npm run build --workspace=@yigitkonur/parasut-node-sdk",
+    "build:mcp": "npm run build --workspace=@yigitkonur/parasut-mcp-server",
+    "typecheck": "npm run typecheck --workspaces",
+    "lint": "npm run lint --workspaces --if-present",
+    "test": "npm run test --workspaces --if-present",
+    "clean": "rm -rf packages/*/dist packages/*/node_modules"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yigitkonur/parasut-node-sdk-mcp.git"
+  },
+  "keywords": [
+    "parasut",
+    "para\u015f\u00fct",
+    "sdk",
+    "mcp",
+    "typescript",
+    "e-fatura",
+    "e-invoice",
+    "turkey",
+    "accounting",
+    "api"
+  ],
+  "author": "Yigit Konur <yigit@konur.dev>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/yigitkonur/parasut-node-sdk-mcp/issues"
+  },
+  "homepage": "https://github.com/yigitkonur/parasut-node-sdk-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}