@devoplus/one-sdk 0.0.0-stage → 0.2.0-next.112

package/bin/accessRequest.d.mts

@@ -0,0 +1,96 @@
+// accessRequest.mjs tipleri — Devoplus One MCP sunucusu ve TypeScript tüketicileri için. Davranış .mjs'tedir.
+
+export declare class AccessRequestError extends Error {
+  readonly status: number | undefined
+  readonly code: string | undefined
+  constructor(message: string, details?: { status?: number; code?: string })
+}
+
+export type AccessRequestKindName =
+  | 'registration'
+  | 'installation'
+  | 'dexa-query'
+  | 'dexa-command'
+  | 'app-permission'
+  | 'scope'
+  | 'new-query'
+
+export interface AccessRequestKind {
+  wire: string
+  label: string
+  required: readonly string[]
+  optional: readonly string[]
+  audience: 'platform' | 'company'
+}
+
+export declare const KINDS: Readonly<Record<AccessRequestKindName, AccessRequestKind>>
+export declare const LIMITS: Readonly<{
+  justification: number
+  description: number
+  draftSql: number
+  title: number
+  permissionName: number
+  additionalPermissions: number
+}>
+
+/** Kayıt talebinin ek izni: `One.<Uygulama>.<Eylem>` kodu + Türkçe ad (zorunlu) + İngilizce ad. */
+export interface AdditionalPermissionInput {
+  code: string
+  nameTr: string
+  nameEn?: string | undefined
+}
+
+export interface AccessRequestFields {
+  appSlug?: string | undefined
+  justification?: string | undefined
+  titleTr?: string | undefined
+  titleEn?: string | undefined
+  portalKey?: string | undefined
+  queryKey?: string | undefined
+  permissionCode?: string | undefined
+  permissionNameTr?: string | undefined
+  permissionNameEn?: string | undefined
+  userGroupId?: string | undefined
+  scope?: string | undefined
+  description?: string | undefined
+  draftSql?: string | undefined
+  /** registration: uygulama içi izinler (en çok 16). */
+  additionalPermissions?: readonly AdditionalPermissionInput[] | undefined
+}
+
+export type AccessRequestBody = { kind: string; appSlug: string } & Record<string, string | AdditionalPermissionInput[]>
+
+/** `GET api/v1/One/access-requests/context` — oturum portalı. */
+export interface PortalContext {
+  portalId: string
+  portalName: string
+  /** Portaldaki var olan bir kurulumun anahtarı; yoksa `null`. */
+  portalKey: string | null
+}
+
+/** Sunucunun talep satırı (backend `OneAccessRequestResponse`). */
+export interface AccessRequestRow {
+  id: string
+  kind: string
+  audience: string
+  status: string
+  appSlug: string
+  [field: string]: unknown
+}
+
+export interface AccessRequestClientOptions {
+  apiBase: string
+  accessToken: string
+  fetch?: typeof fetch
+}
+
+export declare function resolveKind(value: unknown): AccessRequestKindName | undefined
+export declare function buildAccessRequest(kind: string, fields?: AccessRequestFields): AccessRequestBody
+export declare function submitAccessRequest(options: AccessRequestClientOptions, body: AccessRequestBody): Promise<AccessRequestRow>
+export declare function listMyAccessRequests(options: AccessRequestClientOptions): Promise<AccessRequestRow[]>
+export declare function getAccessRequest(options: AccessRequestClientOptions, id: string): Promise<AccessRequestRow>
+export declare function describeAccessRequest(row: Partial<AccessRequestRow>): string
+export declare function buildAdditionalPermissions(value: unknown): Array<{ code: string; nameTr: string; nameEn?: string }>
+export declare function parsePermissionOptions(trValues: readonly string[], enValues?: readonly string[]): AdditionalPermissionInput[]
+export declare function getPortalContext(options: AccessRequestClientOptions): Promise<PortalContext>
+export declare function describePortalContext(context: Partial<PortalContext>): string

package/bin/accessRequest.mjs

@@ -0,0 +1,340 @@
+// Devoplus One ERİŞİM TALEBİ istemcisi (D-75). `one request` komutu ve Devoplus One MCP sunucusu AYNI modülü kullanır;
+// ikisi aynı backend ucunu (`api/v1/One/access-requests`) çağırır.
+//
+// ⛔ Talep YENİ BİR YETKİ YOLU AÇMAZ: yalnız yöneticiye bir istek bırakır. Gönderenin kimliği ve portalı OTURUMDAN
+// (kullanıcının kendi erişim belirtecinden) gelir; bu modül gövdeye portal ya da kişi YAZMAZ.
+//
+// Burada yalnız gövdenin kurulması, türe göre ZORUNLU alanların varlığı, uzunluk ve sayı sınırları denetlenir. Biçim
+// kuralları (kısa ad, portal anahtarı, izin kodu, sorgu anahtarı, yetki alanı) sunucudadır; sunucunun reddi
+// açıklamasıyla birlikte kullanıcıya taşınır. İki yerde tutulan biçim kuralı zamanla ayrışırdı.
+
+export class AccessRequestError extends Error {
+  /**
+   * @param {string} message kullanıcıya gösterilecek Türkçe metin
+   * @param {{ status?: number, code?: string }} [details]
+   */
+  constructor(message, details = {}) {
+    super(message)
+    this.name = 'AccessRequestError'
+    this.status = details.status
+    this.code = details.code
+  }
+}
+
+/** Sunucu sınırları — backend `OneAccessRequest` / `OneApp` / `OneAppPermission` sabitleriyle aynı. */
+export const LIMITS = {
+  justification: 2000,
+  description: 2000,
+  draftSql: 20000,
+  title: 120,
+  permissionName: 120,
+  additionalPermissions: 16,
+}
+
+/**
+ * Talep türleri: komut adı → tel adı (backend `OneAccessRequestNames`) + zorunlu alanlar + kime düşer.
+ * `audience: 'platform'` → platform yöneticisi; `'company'` → talebin portalının şirket yöneticisi (küresel yönetici de
+ * onaylayabilir). Kayıt talebi 19.10.2026'dan beri şirket yöneticisine düşer; yetki alanı platformda kalır.
+ */
+export const KINDS = {
+  registration: {
+    wire: 'registration',
+    label: 'Yeni uygulama kaydı',
+    required: ['titleTr'],
+    // `additionalPermissions`: uygulama içi izinler kayıtla birlikte istenir; onayda kataloğa girer (19.10.2026).
+    optional: ['titleEn', 'additionalPermissions'],
+    audience: 'company',
+  },
+  installation: {
+    wire: 'installation',
+    label: 'Uygulamanın portala kurulması',
+    // Portal anahtarını sunucu portalın adından belirler (örn. "Süvari Portal" için suvari); elle seçilemez.
+    // `portalKey` yalnız eski istemcilerle uyumluluk için kabul edilir, sunucu onu yok sayar (19.10.2026).
+    required: [],
+    optional: ['portalKey'],
+    audience: 'company',
+  },
+  'dexa-query': {
+    wire: 'dexaQuery',
+    label: 'DEXA okuma sorgusu izni',
+    required: ['queryKey'],
+    optional: [],
+    audience: 'company',
+  },
+  'dexa-command': {
+    wire: 'dexaCommand',
+    label: 'ERP\'ye yazan DEXA işlemi izni',
+    required: ['queryKey'],
+    optional: [],
+    audience: 'company',
+  },
+  'app-permission': {
+    wire: 'appPermission',
+    label: 'Uygulama izninin bir gruba atanması',
+    required: ['permissionCode'],
+    optional: ['permissionNameTr', 'permissionNameEn', 'userGroupId'],
+    audience: 'company',
+  },
+  scope: {
+    wire: 'scope',
+    label: 'Yetki alanı (scope)',
+    required: ['scope'],
+    optional: [],
+    audience: 'platform',
+  },
+  'new-query': {
+    wire: 'newQuery',
+    label: 'Henüz olmayan bir sorgu için iş talebi',
+    required: ['description'],
+    optional: ['draftSql'],
+    audience: 'company',
+  },
+}
+
+/** Alanların kullanıcıya görünen adları (hata metinleri için). */
+const FIELD_LABELS = {
+  appSlug: 'uygulamanın kısa adı',
+  justification: 'gerekçe',
+  titleTr: 'uygulamanın Türkçe adı',
+  titleEn: 'uygulamanın İngilizce adı',
+  portalKey: 'portal anahtarı',
+  queryKey: 'sorgu anahtarı',
+  permissionCode: 'izin kodu',
+  permissionNameTr: 'iznin Türkçe adı',
+  permissionNameEn: 'iznin İngilizce adı',
+  userGroupId: 'kullanıcı grubu kimliği',
+  scope: 'yetki alanı',
+  description: 'sorgu tarifi',
+  draftSql: 'SQL taslağı',
+}
+
+const LENGTH_OF = {
+  justification: LIMITS.justification,
+  description: LIMITS.description,
+  draftSql: LIMITS.draftSql,
+  titleTr: LIMITS.title,
+  titleEn: LIMITS.title,
+  permissionNameTr: LIMITS.permissionName,
+  permissionNameEn: LIMITS.permissionName,
+}
+
+/** Tel adı ya da komut adı → komut adı. Harf duyarsız (`dexaQuery` = `dexa-query`). */
+export function resolveKind(value) {
+  const text = String(value ?? '').trim().toLowerCase().replace(/_/g, '-')
+  for (const [name, kind] of Object.entries(KINDS)) {
+    if (name === text || kind.wire.toLowerCase() === text) return name
+  }
+  return undefined
+}
+
+function clean(value) {
+  if (value === undefined || value === null) return undefined
+  const text = String(value).trim()
+  return text === '' ? undefined : text
+}
+
+/**
+ * Talep gövdesini kurar. İlgisiz alanlar gövdeye girmez (sunucu yok sayardı; göndermemek talebi okuyan yöneticiye
+ * gösterilen içeriği daraltır). Hata → `AccessRequestError`, ağ çağrısı YAPILMADAN.
+ *
+ * @param {string} kind komut adı ya da tel adı
+ * @param {Record<string, unknown>} fields `appSlug`, `justification` + türün alanları
+ */
+export function buildAccessRequest(kind, fields = {}) {
+  const name = resolveKind(kind)
+  if (!name)
+    throw new AccessRequestError(`Talep türü tanınmadı: "${kind}". Geçerli türler: ${Object.keys(KINDS).join(', ')}.`)
+  const spec = KINDS[name]
+  const appSlug = clean(fields.appSlug)?.toLowerCase()
+  if (!appSlug) throw new AccessRequestError('Uygulamanın kısa adı zorunludur (one.manifest.json dosyasındaki app.slug).')
+
+  const body = { kind: spec.wire, appSlug }
+  for (const key of ['justification', ...spec.required, ...spec.optional]) {
+    if (key === 'additionalPermissions') {
+      const list = buildAdditionalPermissions(fields[key])
+      if (list.length > 0) body[key] = list
+      continue
+    }
+    const value = clean(fields[key])
+    if (value === undefined) {
+      if (spec.required.includes(key))
+        throw new AccessRequestError(`"${spec.label}" talebi için ${FIELD_LABELS[key]} zorunludur.`)
+      continue
+    }
+    const max = LENGTH_OF[key]
+    if (max !== undefined && value.length > max)
+      throw new AccessRequestError(`${capitalize(FIELD_LABELS[key])} en çok ${max} karakter olabilir (${value.length}).`)
+    body[key] = value
+  }
+  return body
+}
+
+/**
+ * Kayıt talebinin ek izinleri: `[{ code, nameTr, nameEn? }]`, en çok 16. Burada yalnız yapı, sayı, uzunluk ve birebir
+ * yinelenen kod denetlenir; kodun biçimi (`One.<Ad>.<Eylem>`) ve uygulamanın ad alanında olması SUNUCUDADIR.
+ *
+ * @param {unknown} value
+ * @returns {Array<{ code: string, nameTr: string, nameEn?: string }>}
+ */
+export function buildAdditionalPermissions(value) {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new AccessRequestError('Ek izinler bir liste olmalı: [{ code, nameTr, nameEn? }].')
+  if (value.length > LIMITS.additionalPermissions)
+    throw new AccessRequestError(`En çok ${LIMITS.additionalPermissions} ek izin istenebilir (${value.length}).`)
+  const seen = new Set()
+  return value.map((item, i) => {
+    const code = clean(item?.code)
+    const nameTr = clean(item?.nameTr)
+    const nameEn = clean(item?.nameEn)
+    const at = `${i + 1}. ek izin`
+    if (!code) throw new AccessRequestError(`${at}: izin kodu zorunludur (One.<Uygulama>.<Eylem>).`)
+    if (!nameTr) throw new AccessRequestError(`${at} (${code}): iznin Türkçe adı zorunludur.`)
+    if (code.length > 200) throw new AccessRequestError(`${at}: izin kodu en çok 200 karakter olabilir.`)
+    for (const [label, name] of [['Türkçe', nameTr], ['İngilizce', nameEn]])
+      if (name !== undefined && name.length > LIMITS.permissionName)
+        throw new AccessRequestError(`${at} (${code}): iznin ${label} adı en çok ${LIMITS.permissionName} karakter olabilir.`)
+    if (seen.has(code)) throw new AccessRequestError(`Ek izin kodu iki kez yazılmış: ${code}.`)
+    seen.add(code)
+    return nameEn === undefined ? { code, nameTr } : { code, nameTr, nameEn }
+  })
+}
+
+/**
+ * Komut satırının `--permission <kod>=<Türkçe ad>` ve `--permission-en <kod>=<İngilizce ad>` değerlerini ek izin
+ * listesine çevirir. İngilizce ad yalnız `--permission` ile verilmiş bir koda eklenebilir.
+ *
+ * @param {readonly string[]} trValues
+ * @param {readonly string[]} [enValues]
+ */
+export function parsePermissionOptions(trValues, enValues = []) {
+  const split = (raw, option) => {
+    const text = String(raw ?? '')
+    const at = text.indexOf('=')
+    if (at <= 0) throw new AccessRequestError(`${option} "<kod>=<ad>" biçiminde olmalı: ${text}`)
+    return [text.slice(0, at).trim(), text.slice(at + 1).trim()]
+  }
+  const list = trValues.map((raw) => {
+    const [code, nameTr] = split(raw, '--permission')
+    return { code, nameTr }
+  })
+  for (const raw of enValues) {
+    const [code, nameEn] = split(raw, '--permission-en')
+    const item = list.find((p) => p.code === code)
+    if (!item) throw new AccessRequestError(`--permission-en için önce aynı kodla --permission verin: ${code}`)
+    item.nameEn = nameEn
+  }
+  return list
+}
+
+function capitalize(text) {
+  return text.charAt(0).toLocaleUpperCase('tr-TR') + text.slice(1)
+}
+
+/** API tabanı `https://.../` biçiminde olmalı; uç yolu ona eklenir. */
+function endpoint(apiBase, path) {
+  // Belirteç bu adrese gider: düz http yalnız yerel geliştirme adresinde (RFC 6750 §5.3).
+  const base = apiBase ?? ''
+  if (!/^https:\/\/[^\s/]+(\/[^\s]*)?\/$/.test(base) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?\/([^\s]*\/)?$/.test(base))
+    throw new AccessRequestError(`API tabanı "https://.../" biçiminde ve "/" ile bitmeli (http yalnız localhost): ${apiBase}`)
+  return new URL(`api/v1/One/access-requests${path}`, apiBase).toString()
+}
+
+/** Sunucunun ProblemDetails yanıtını kullanıcı metnine çevirir; gövde yoksa durum koduna göre sabit cümle. */
+async function failure(response) {
+  let detail
+  let code
+  try {
+    const problem = await response.json()
+    detail = typeof problem?.detail === 'string' ? problem.detail : undefined
+    code = typeof problem?.code === 'string' ? problem.code : undefined
+  } catch {
+    // gövdesiz 401/403 — aşağıdaki sabit metin
+  }
+  const fallback =
+    response.status === 401
+      ? 'Oturumunuz geçersiz ya da süresi dolmuş; yeniden giriş yapın.'
+      : response.status === 403
+        ? 'Bu talebi gönderme yetkiniz yok.'
+        : response.status === 429
+          ? 'Çok fazla talep gönderdiniz; bir süre sonra yeniden deneyin.'
+          : `Devoplus isteği başarısız oldu (HTTP ${response.status}).`
+  return new AccessRequestError(detail ?? fallback, { status: response.status, code })
+}
+
+/**
+ * @typedef {{ apiBase: string, accessToken: string, fetch?: typeof fetch }} ClientOptions
+ */
+
+async function call(options, path, init = {}) {
+  const doFetch = options.fetch ?? fetch
+  if (!options.accessToken) throw new AccessRequestError('Oturum yok; önce giriş yapın.', { status: 401 })
+  let response
+  try {
+    response = await doFetch(endpoint(options.apiBase, path), {
+      ...init,
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${options.accessToken}`,
+        ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+      },
+    })
+  } catch (error) {
+    if (error instanceof AccessRequestError) throw error
+    throw new AccessRequestError('Devoplus API\'ye ulaşılamadı.')
+  }
+  if (!response.ok) throw await failure(response)
+  return response.json()
+}
+
+/** Talebi gönderir. Dönüş: sunucunun talep satırı (`id`, `status` …). */
+export function submitAccessRequest(options, body) {
+  return call(options, '', { method: 'POST', body: JSON.stringify(body) })
+}
+
+/** Çağıranın kendi talepleri (en yeni önce). */
+export function listMyAccessRequests(options) {
+  return call(options, '/mine')
+}
+
+/**
+ * Oturum portalının bağlamı: `{ portalId, portalName, portalKey | null }`. Kurulum talebinde kullanıcıya portal adresi
+ * sormamak için okunur; `portalKey` portaldaki var olan bir kurulumun anahtarıdır, yoksa `null`.
+ */
+export function getPortalContext(options) {
+  return call(options, '/context')
+}
+
+/** Portal bağlamını tek satırlık Türkçe özete çevirir. */
+export function describePortalContext(context) {
+  const name = context?.portalName ? String(context.portalName) : 'adı okunamadı'
+  const key =
+    typeof context?.portalKey === 'string' && context.portalKey
+      ? `kısa ad (portal anahtarı): ${context.portalKey}`
+      : 'bu portalda henüz kısa ad yok; kurulum onayında sunucu portalın adından belirler'
+  return `Portal: ${name} (kimlik ${context?.portalId ?? '?'}); ${key}`
+}
+
+/** Tek talep — çağıran talep sahibi değilse sunucu 404 döner. */
+export function getAccessRequest(options, id) {
+  const text = String(id ?? '').trim()
+  if (!/^[0-9a-f]{24}$/i.test(text)) throw new AccessRequestError(`Talep kimliği 24 karakterlik onaltılık olmalı: ${id}`)
+  return call(options, `/${text}`)
+}
+
+const STATUS_LABELS = { pending: 'Bekliyor', approved: 'Onaylandı', rejected: 'Reddedildi' }
+
+/** Talep satırını tek satırlık Türkçe özete çevirir (CLI listesi ve MCP yanıtı). */
+export function describeAccessRequest(row) {
+  const name = resolveKind(row?.kind)
+  const label = name ? KINDS[name].label : String(row?.kind ?? '?')
+  const subject =
+    row?.portalKey ?? row?.queryKey ?? row?.permissionCode ?? row?.scope ?? row?.titleTr ?? row?.description ?? ''
+  const status = STATUS_LABELS[row?.status] ?? String(row?.status ?? '?')
+  const parts = [`${row?.id ?? '?'}  ${status.padEnd(10)}  ${row?.appSlug ?? '?'}, ${label}`]
+  if (subject) parts.push(`: ${String(subject).slice(0, 80)}`)
+  const extra = Array.isArray(row?.additionalPermissions) ? row.additionalPermissions.length : 0
+  if (extra > 0) parts.push(` (+${extra} ek izin)`)
+  if (row?.decisionNote) parts.push(`; not: ${row.decisionNote}`)
+  if (row?.resolvedQueryKey) parts.push(`; sorgu anahtarı: ${row.resolvedQueryKey}`)
+  return parts.join('')
+}

package/bin/appOps.d.mts

@@ -0,0 +1,97 @@
+// appOps.mjs tipleri — Devoplus One MCP sunucusu ve TypeScript tüketicileri için. Davranış .mjs'tedir.
+
+export declare class AppOpsError extends Error {
+  readonly status: number | undefined
+  readonly code: string | undefined
+  constructor(message: string, details?: { status?: number; code?: string })
+}
+
+export declare const SLUG_RE: RegExp
+export declare const SLUG_MAX: number
+export declare const PORTAL_KEY_RE: RegExp
+export declare const VERSION_RE: RegExp
+export declare const DAYS_DEFAULT: number
+export declare const DAYS_MAX: number
+export declare const PREVIEW_HOST_BASE: string
+export declare const NOT_CONFIGURED_MESSAGE: string
+export declare const INSIGHTS_NOT_CONFIGURED_MESSAGE: string
+export declare const ROLLBACK_WARNING: string
+
+export type DeploymentAction = 'deploy' | 'promote' | 'rollback'
+export declare const ACTIONS: Readonly<Record<DeploymentAction, string>>
+export declare const COMMAND_ACTIONS: Readonly<{ publish: 'deploy'; promote: 'promote'; rollback: 'rollback' }>
+
+export interface AppOpsClientOptions {
+  apiBase: string
+  accessToken: string
+  fetch?: typeof fetch
+}
+
+export interface DeploymentFields {
+  action?: string | undefined
+  portalKey?: string | undefined
+  toVersion?: string | undefined
+}
+
+export interface DeploymentRequestBody {
+  action: DeploymentAction
+  portalKey?: string
+  toVersion?: string
+}
+
+/** Backend yanıtı (C5): 202 `{ id, status, pipelineUrl? }`. */
+export interface DeploymentResult {
+  id: string
+  status: 'queued' | 'not_configured' | (string & {})
+  pipelineUrl?: string
+}
+
+/** Liste satırı — C5 alanları; sunucu fazlasını taşıyabilir. */
+export interface DeploymentRow extends Partial<DeploymentResult> {
+  action?: string
+  portalKey?: string
+  toVersion?: string
+  createdAt?: string
+  [field: string]: unknown
+}
+
+export interface AppInsights {
+  configured: boolean
+  from?: string
+  to?: string
+  totals?: { requests?: number; errors?: number; cpuP50Ms?: number; cpuP99Ms?: number }
+  daily?: Array<{ date: string; requests: number; errors: number }>
+  recentErrors?: Array<{ time: string; message: string; path?: string }>
+  jobs?: { failed?: number }
+}
+
+export type OpsCommand = 'publish' | 'promote' | 'rollback' | 'deployments' | 'status'
+
+export interface OpsArgs {
+  json: boolean
+  portalKey: string | undefined
+  app: string | undefined
+  toVersion?: string | undefined
+  yes?: boolean
+  days?: number
+}
+
+export declare function checkSlug(value: unknown): string
+export declare function checkPortalKey(value: unknown): string | undefined
+export declare function checkDays(value: unknown): number
+export declare function buildDeploymentRequest(fields?: DeploymentFields): DeploymentRequestBody
+export declare function requestDeployment(options: AppOpsClientOptions, slug: string, body: DeploymentFields): Promise<DeploymentResult>
+export declare function listDeployments(options: AppOpsClientOptions, slug: string, portalKey?: string): Promise<DeploymentRow[]>
+export declare function getInsights(
+  options: AppOpsClientOptions,
+  slug: string,
+  query?: { portalKey?: string | undefined; days?: number | string | undefined },
+): Promise<AppInsights>
+export declare function previewAddress(slug: string, portalKey: string | undefined): string | undefined
+export declare function describeDeployment(row: Partial<DeploymentRow>): string
+export declare function describeDeploymentResult(
+  result: Partial<DeploymentResult>,
+  request: { action: string; slug: string; portalKey?: string | undefined },
+): string
+export declare function describeInsights(insights: Partial<AppInsights> | undefined): string
+export declare function parseOpsArgs(command: OpsCommand, argv: readonly string[]): OpsArgs